Обработка аргументов с помощью JCommander #

Васильев Андрей Михайлович

Версии презентации

Аргументы приложения #

  • Приложение при старте может получить некоторый набор строк, аргументов, которые были указаны при запуске приложения
  • Приложение может использовать их для настройки собственного поведения
  • Разработчик приложения волен самостоятельно определить формат обработки строк
  • Разумно использовать подходы, которые известны пользователю в результате работы с другими приложениями, сделать приложение «интуитивно понятным»
  • Существует множество библиотек для JVM, позволяющих выполнить обработку передаваемых строк. Рассмотрим JCommander

Официальная документация: https://jcommander.org/

JavaDoc-документация: https://javadoc.io/doc/org.jcommander/jcommander/latest/index.html

Альтернативное Java-решение: https://picocli.info/

Подключение библиотеки #

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

Gradle-описание зависимости для подключения: "org.jcommander:jcommander:3.0"

При использовании Gradle без дополнений её необходимо добавить в файл build.gradle.kts в раздел dependencies: 

dependencies {
    implementation("org.jcommander:jcommander:3.0")
}

При использовании шаблона лабораторной добавьте строку в файл build.properties.json в список dependencies

Концептуальный подход JCommander #

diagram

  • Необходимо описать и создать объекты-хранители аргументов
  • Необходимо создать ключевой объект библиотеки JCommander
    • Объект JCommander создаётся путём взаимодействия с объектом-строителем
    • Объекту-строителю передаётся список объектов-хранителей аргументов
  • Созданному объекту передаются аргументы командной строки
    • При работе JCommander опирается на мета-информацию, расположенную в аннотациях к свойствам объектам-хранителям аргументов
    • Объект-хранитель вместе с хранением описывает поддерживаемые аргументы
    • В случае ошибки обработки аргументов выбрасывается исключение ParameterException

Описание объекта-хранителя аргументов # 

@Parameters(separators = "=")
class Args {
    @Parameter
    var targets: List<String> = arrayListOf()
    @Parameter(names = ["-bf", "--buildFile"],
               description = "The build file")
    var buildFile: String? = null
    @Parameter(names = ["--checkVersions"],
               description = "Check if there are any newer versions")
    var checkVersions = false
}
  • Аннотация Parameters определяет общие правила обработки строк для данного объекта, не обязательна для использования
    • По умолчанию separators = " " — аргументы разбираются только в формате ключ значение
    • С помощью аргумента separators="=" включается разбор в формате ключ=значение; при этом разбор через пробел отключается
  • Конкретные свойства обозначаются для записи с помощью аннотации @Parameter
  • Свойства должны быть изменяемыми
  • Свойства могут иметь значения по умолчанию
  • Названия ключей для свойств объектов определяется с помощью names
  • Рекомендуется добавлять описание параметра, чтобы предоставить пользователю содержательную информацию по назначению аргумента

Создание и вызов JCommander # 

val commander: JCommander = 
    JCommander
        .newBuilder()
        .addObject(commonParameters)
        .build()
  • Создаём объект-строитель путём вызова статического метода newBuilder()
  • Добавляем объекты-хранители аргументов с помощью addObject()
  • Завершаем создание путём вызова метода build()
  • Передаём аргументы путём вызова метода parse(), принимающего произвольное количество строк
commander.parse("--enable", "--size", "15")
val arguments: Array<String> = ...
commander.parse(*arguments)
  • Обработанные аргументы будут сохранены в объект commonParameters
  • Если строки не смогут быть обработаны, будет выброшено исключение ParameterException

Преобразование в сложные типы данных #

JCommander постарается автоматически преобразовать данные из строкового представления в тип данных свойства класса для: логических полей, целых чисел, вещественных чисел и строк

Для других сложных типов данных, классов можно предоставить класс-преобразователь, который должен реализовывать следующий Java-интерфейс:

public interface IStringConverter<T> {
  T convert(String value);
}

Например для UUID на Kotlin такой класс может выглядеть следующим образом: 

class UUIDConverter : IStringConverter<UUID> {
    override fun convert(parameter: String): UUID = 
        UUID.fromString(parameter)
}

В целевом объекте-хранителе аргументов необходимо сослаться на данный преобразователь следующим образом:

@Parameter(names=["--id"], converter = UUIDConverter::class)
var someId: UUID? = null
  • Если во время преобразования строки к UUID возникнет ошибка, то будет выброшено исключение IllegalArgumentException
  • Конвертор необходимо явно указывать для каждого поля в параметрах аннотации Parameter, для которого необходимо выполнить преобразование

Обязательные аргументы #

Аннотация Parameter позволяет указать аргумент как обязательный:

@Parameter(names=["--data-one"], required = true)
var dataOne: Int = 0

JCommander проверяет обязательные аргументы не по значению поля после обработки, а по паре «значение по умолчанию + тип поля»:

  1. Если у поля есть непустое значение по умолчанию и тип не примитивный (например, var dataOne: String = "default"), проверка обязательности пропускается, и при отсутствии аргумента исключение не выбрасывается.
  2. Если поле инициализировано null (например, var dataOne: Int? = null), тип примитивный (var dataOne: Int = 0) или значение по умолчанию пустое, при отсутствии аргумента выбрасывается ParameterException.

Поэтому обязательные аргументы рекомендуется описывать так:

@Parameter(names=["--data-one"], required = true)
var dataOne: Int? = null

Факт отсутствия исключения не убеждает компилятор Kotlin в наличие не-null-значения в свойстве объекта.

Команды #

Приложения с командным интерфейсом зачастую предоставляют ряд связных между собой действий, каждое из которых имеет свой собственный набор аргументов

  • Склонировать репозиторий: git clone <REPOSITORY>
  • Создать новую ветку в репозитории git switch --create <BRANCH>

Названием команды обычно выступает первый позиционный аргумент приложения

Согласно концепции JCommander

  • Список аргументов команды описывается в отдельном объекте
  • Объекты регистрируются как команды, указывается уникальный идентификатор команды
  • Объекты-команды описываются также как объекты-параметры, только регистрируются по-другому
  • После обработки аргументов у объекта JCommander можно узнать строковый идентификатор команды, которая была определена, через свойство parsedCommand

JCommander с командами #

diagram

  • Необходимо описать классы для сохранения аргументов для каждой команды
  • При создании объекта JCommander необходимо связать название команды с объектами-хранителями аргумента команды
  • Во время обработки аргументов первый используется для определения команды
  • Данные будут записаны в объект-хранитель соответствующей команды

Описание объекта-хранителя команды #

Описание не отличается от обычного объекта-хранителя:

  • Аннотация Parameters используется для описания поведения объекта-хранителя
  • Аннотация Parameter используется для описания конкретного аргумента
@Parameters(separators = "=",
        commandDescription = "List application entries")
class ListCommand {
    @Parameter(names = ["-s", "--size"],
            description = "Amount of items to display")
    var size: Int = 10
}

Единственным отличием является возможность использования аргумента commandDescription у аннотации Parameters, которая позволяет добавить описание назначения команды

Настройка JCommander для работы с командами # 

val commander: JCommander = 
    JCommander
        .newBuilder()
        .addCommand("list", listCommand)
        .addCommand("build", buildCommand)
        .build()
  • Создаём объект-строитель путём вызова метода newBuilder()
  • Добавляем список объектов-хранителей аргументов команд
  • При добавлении команды указывается её уникальное имя
commander.parse("list", "--size=15")
val arguments: Array<String> = ...
commander.parse(*arguments)
val command: String? = commander.parsedCommand
if (command == null) {
  // Команда не передана — сообщение об ошибке и ненулевой код возврата
} else if (command == "list") {
  ... // Обрабатываем данные внутри listCommand
} else if (command == "build") {
  ... // Обрабатываем данные внутри buildCommand
}

Общие параметры и команды #

Общие для всех команд параметры описываются отдельным объектом-хранителем и добавляются в построитель методом addObject(). Общие параметры указываются в командной строке до имени команды

val commonParameters = CommonParameters()
val commander: JCommander =
    JCommander
        .newBuilder()
        .addObject(commonParameters)
        .addCommand("list", listCommand)
        .addCommand("build", buildCommand)
        .build()
// --triangles-file="data.csv" list
commander.parse(*arguments)

Если команда не передана, parse() не выбрасывает исключение, а parsedCommand остаётся равным null. Такой случай необходимо проверять явно и завершать приложение с ненулевым кодом возврата

Справка по использованию #

JCommander способен сформировать справку по использованию всех доступных аргументов, их значений по умолчанию и т.д.

Для вывода этой информации на стандартный поток вывода, вызовите метод usage() на объекте JCommander после добавления к нему объектов и команд

Usage: <main class> [command] [command options]
  Commands:
    list      List application entries
      Usage: list [options]
        Options:
          -s, --size
            Amount of items to display
            Default: 10

    update      Update application entry
      Usage: update [options]
        Options:
        * -i, --id
            Id of the entry to update

Аргументы, помеченные *, являются обязательными

Размещение аргументов в файле #

При разработке приложения с большим количеством аргументов надо иметь возможность удобным образом переключаться между разными наборами аргументов

Помимо использования модульных тестов JCommander предоставляет возможность считывания списка аргументов из файла с помощью @-синтаксиса

commander.parse("@params.txt")

Из файла params.txt, который находится в текущем рабочем каталоге:

  • Будут считаны все строки
  • Строки, начинающиеся с символа #, будут проигнорированы
  • Оставшиеся строки разбиты на слова, будет получен список аргументов
  • Внутри данных аргументов могут находиться @-аргументы

Данный подход удобнее постоянного редактирования конфигурации запуска Gradle-задачи