Шпаргалки Java программиста 10: Lombok

Lombok @Data

@Data — это удобная сокращённая аннотация, которая содержит в себе возможности из @ToString, @EqualsAndHashCode, @Getter / @Setter и @RequiredArgsConstructor. Другими словами, @Data генерирует весь бойлерплейт код, который обычно связан с обычными POJO (Plain Old Java Objects) и бинами: методы получения значений для всех полей, методы установки значений для не final полей, подходящий toString, equals и hashCode для этих полей, конструктор, инициализирующий все final поля и все не final поля, у которых нет выражения инициализации, и которые помечены @NonNull, для того чтобы гарантировать, что поле никогда не будет null.

@Data — это всё равно, что иметь неявные @Getter, @Setter, @ToString, @EqualsAndHashCode и @RequiredArgsConstructor для класса (с исключением что никаких конструкторов не генерируется, если уже есть явно написанный конструктор). Однако параметры этих аннотаций (callSuper, includeFieldNames и exclude) не могут быть установлены с @Data. Если вам нужно установить значение этих параметров отличное от значения по умолчанию, то просто явно добавьте эти аннотации. @Data достаточно умён, чтобы учитывать их.

Все сгенерированные методы получения значений и установки значений будут с модификатором доступа public. Чтобы переопределить уровень доступа, добавьте @Getter, @Setter к полю или классу. Вы можете также использовать эти аннотации (комбинируя их с AccessLevel.NONE), чтобы подавить генерацию методов установки значений и/или методов получения значений.

Все поля помеченные как transient не будут рассматриваться в hashCode и equals. Все статические поля будут пропускаться полностью (не рассматриваются любыми сгенерированными методами, и для них не будет сгенерировано методов получения/установки значений).

Если класс уже содержит метод с таким же именем и количеством параметров, как метод, который должен быть сгенерирован, то метод не генерируется, и ошибок и предупреждений не возникает. Например, если уже есть метод с сигнатурой equals(AnyType param), то метод equals не будет сгенерирован, несмотря на то что технически это может быть совершенно другой метод, так как у него другой тип параметра. То же правило применяется для конструктора (при наличии явного конструктора @Data не генерирует конструкторов), так же как и для toString, equals, методов получения значений, методов установки значений. Вы можете пометить любой конструктор или метод @lombok.experimental.Tolerate, чтобы скрыть его от Lombok.

@Data может обрабатывать шаблонные параметры для полей. Для того чтобы уменьшить бойлерплейт-код при создании объектов для классов с шаблонами, вы можете использовать параметр staticConstructor, чтобы сгенерировать приватный конструктор, а также статический метод, возвращающий новый экземпляр. В этом случае javac будет выводить тип переменной. Таким образом, с объявлением класса @Data ( staticConstructor = “of” ) class Foo < private T x ; >, вы можете создавать экземпляры класса Foo так: Foo . of ( 5 ) ; , вместо new Foo ( 5 ) ; .

Как использовать библиотеку Lombok

В предыдущей статье мы рассмотрели, подключить библиотеку Lombok к проекту и как установить плагин в IDE. Сегодня же мы расскажем, как использовать Lombok для уменьшения шаблонного кода при разработке программ.

Как использовать Lombok

При написании кода используются аннотации Lombok. С помощью аннатоций Lombok на этапе компиляции генерирует шаблонный код. С помощью аннотаций Lombok можно генерировать конструкторы классов, геттеры и сеттеры, методы toString, equals и hashCode. Давайте вкратце рассмотрим использование Lombok в работе.

Сеттеры и геттеры

Для генерации сеттеров и геттеров используются аннотации @Setter и @Getter, соответственно. Эти аннотации удобно навесить на POJO класс со множеством полей, дабы не генерировать шаблонный код самому.

Здесь мы объявили класс Person с тремя полями и указали аннотации @Getter и @Setter. Если вы правильно подключили Lombok и установили плагин, то он сразу же создаст геттеры и сеттеры. Теперь можно воспользоваться созданными методами:

Примечание: если вы определите какой-либо геттер или сеттер в классе, то Lombok не будет его трогать при генерации кода. То есть уже определённые методы будут иметь приоритет над вновь создаваемыми. Также для нестатических final полей не будут сгенерированы сеттеры.

Конструкторы

Рутинное написание типовых конструкторов можно поручить библиотеке Lombok, аннотировав нужный класс с помощью аннотаций @AllArgsConstructor, @RequiredArgsConstructor и @NoArgsConstructor. Как и следует из названий, эти аннотации приведут к генерированию таких конструкторов:

• @AllArgsConstructor – консктруктор, использующий все поля класса
• @RequiredArgsConstructor – конструктор, использующий все final поля класса
• @NoArgsConstructor – конструктор без параметров

Эти аннотации можно комбинировать между собой и использовать вместе с аннотациями @Getter и @Setter.

Давайте определим класс Person с аннотациями @NoArgsConstructor и @AllArgsConstructor:

Как вы видите, Lombok сгенерировал конструктор без параметров и конструктор со всеми параметрами.

Примечание: при использовании в классе нестатических final полей невозможно использовать аннотацию @NoArgsConstructor, так как в конструкторе без параметров такие поля не будут инициализированы.

Методы toString, equals, и hashCode

Для создания метода toString воспользуйтесь аннотацией @ToString:

Выполнение данного кода выведет в консоль следующий текст:

Методы equals и hashCode генерируются с помощью аннотации @EqualsAndHashCode. Для простых классов вполне ясно и понятно использовать генерирование этих методов, но в нетривиальных случаях рекомендуется создавать equals и hashCode вручную (или средствами IDE).

Все методы воедино

Зачастую аннотации @Getter, @Setter, @ToString, @EqualsAndHashCode, и @RequiredArgsConstructor используются вместе для одного класса. Для такого типового подхода существует аннотация @Data, объединяющая все перечисленные аннотации.

С помощью аннотации @Data будут сгенерированы геттеры и сеттеры, конструктор со всеми final полями, методы toString, equals и hashCode. Эти два класса равнозначны:

Method chaining

Предположим, у нас есть класс с множеством полей. Использовать конструктор со всеми аргументами – не вариант, получится слишком длинный список аргументов. Вызывать по одному сеттеру в каждой строке может быть тоже непрактично. В этом случае можно воспользоваться аннотацией @Builder на нужном классе и использовать любой набор полей для построения объекта:

Начните построение объекта с вызова метода builder(), затем используйте нужные сеттеры, после чего вызовите метод build() для построения объекта.

Логгеры

Библиотеку Lombok можно использовать не только для моделей и POJO, но и для других классов – например, сервисов. Если в классе используется логгер, то генерирование этого поля можно поручить Lombok.

Например, вместо данного кода:

Можно написать следующий код, используя @Slf4j:

В аннотированном классе будет создано такое final поле с именем log.

Помимо @Slf4j, в Lombok есть ещё аннотации @Log и @CommonsLog. Эти аннотации отвечают за генерацию переменных следующих типов:

• @Log – java.util.logging.Logger
• @Slf4j – org.slf4j.Logger
• @CommonsLog – org.apache.commons.logging.Log

NonNull

Если пометить поле аннотацией @NonNull, то в случае, если будет попытка присвоить данному полю значение null, Lombok выбросит исключение:

Такое поведение будет аналогично тому, если бы мы написали в начале конструктора или сеттера проверку на null:

Переменные @var и константы @val

В Lombok есть интересные аннотации @var для обозначения «изменяемых» переменных и @val для констант. Обе эти аннотации применяются для обозначения локальных переменных.

Начиная с Java 10, синтаксис языка позволяет делать то же самое. Можно использовать val для объявления локальной константы и var для объявления локальной переменной. Особенностью данных двух ключевых слов является то, что тип переменной (или константы) будет определён компилятором автоматически. То есть не потребуется указывать тип переменной (константы) вручную:

Данные аннотации можно использовать и в «классическом» стиле:

В этом случае ошибки компиляции не будет, но значение константы не изменится при попытке её переопределить.

Заключение

В данной статье мы рассказали о ключевых возможностях библиотеки Lombok. С помощью Lombok вы можете упростить и ускорить ращработку программ, используя аннотации длягенерирования конструкторов (@AllArgsConstructor, @RequiredArgsConstructor и @NoArgsConstructor), геттеров и сеттеров (@Getter, @Setter), генерировать стандартные методы (@ToString, @EqualsAndHashCode), генерировать поле для логгера (@Log, @Slf4j, @CommonsLog), использовать функциональность val и var в версиях ниже Java 10. Дерзайте!

Конфигурирование lombok

В статье о генерации геттеров и сеттеров я упоминал о конфигурационном файле project lombok. Настало время рассмотреть его подробнее.

Конфигурационный файл project lombok имеет фиксированное имя lombok .config и не привязан к какому-либо заранее оговорённому расположению. Действие lombok .config распространяется на каталог, в котором он расположен и подкаталоги этого каталога. Одновременно в разных каталогах и подкаталогах может располагаться любое количество этих файлов, настройки которых объединяются для каждого конкретного каталога.

При объединении настроек действует два правила — если какой-либо lombok .config , находящийся в текущем каталоге или выше текущего каталога задаёт какую либо опцию, это значение будет использовано при генерации кода. Если разные значения одной и той же настройки задают несколько файлов lombok .config , находящихся в текущем каталоге или выше текущего каталога, будет использовано значение из ближайшего (по иерархии каталогов) к компилируемому файлу.

Опция config . stopBubbling = true запрещают поиск lombok . config в вышестоящих каталогах. Ключевое слово clear перед наименованием опции сбрасывает все изменения от вышестоящих lombok . config и устанавливает для опции значение по умолчанию.

Глобальные опции

Три с половиной опции, которые влияют на поведение всего lombok:

• lombok . addGeneratedAnnotation = false запрещает добавление аннотации @Generated к сгенерированным методам.
• lombok . extern . findbugs . addSuppressFBWarnings = true добавляет аннотацию @SuppressFBWarnings к сгенерированным методам, чтобы FindBugs не пытался их проверять. Установка этой опции в true требует наличия библиотек FindBugs.
• lombok . experimental . flagUsage = [ warning | error ] не совсем глобальная опция. Установка этой опции в warning или error приводит к генерации предупреждений или ошибок при использовании экспериментальных аннотаций.
• config . stopBubbling уже описана выше.

flagUsage можно использовать и с каждым модулем lombok отдельно, вызывая предупреждение или ошибку при использовании этого модуля. Допустимы следующие варианты flagUsage :

• lombok.val.flagUsage
• lombok.nonNull.flagUsage
• lombok.cleanup.flagUsage
• lombok.setter.flagUsage
• lombok.getter.flagUsag
• lombok.toString.flagUsage
• lombok.equalsAndHashCode.flagUsage
• lombok.anyConstructor.flagUsage, lombok.allArgsConstructor.flagUsage, lombok.requiredArgsConstructor.flagUsage, lombok.noArgsConstructor.flagUsage
• lombok.data.flagUsage
• lombok.builder.flagUsage
• lombok.value.flagUsage
• lombok.sneakyThrows.flagUsage
• lombok.synchronized.flagUsage
• lombok.getter.lazy.flagUsage
• lombok.log.apacheCommons.flagUsage, lombok.log.javaUtilLogging.flagUsage, lombok.log.log4j.flagUsage, lombok.log.log4j2.flagUsage, lombok.log.slf4j.flagUsage, lombok.log.xslf4j.flagUsage

Опции настройки аннотаций

Помимо глобальных опций у некоторых аннотаций есть собственные настройки.

@NonNull

• lombok . nonNull . exceptionType = NullPointerException (по умолчанию)
• lombok . nonNull . exceptionType = IllegalArgumentException

Указывает, какое исключение выбрасывать при попытке записать null в @NonNull поле.

@Getter/@Setter

• lombok . accessors . chain = true

Генерирует сеттеры, которые возвращают this вместо void , тем самым позволяя вызывать их цепочкой.

• lombok . accessors . fluent = true

Изменяет имена геттеров и сеттеров, отказывая от стандартных префиксов get и set. Имена методов будут совпадать с именами полей.

• lombok . accessors . prefix += префикс

Эта опция принимает список параметров, то есть можно повторять её несколько раз и каждый раз новый префикс будет добавлен в список. Удалить какой-либо префикс можно использую нотацию lombok . accessors . prefix -= префикс .

Использование списка префиксов довольно туманно: lombok будет удалять префиксы присутствующие в списке из имён полей при генерации соответствующих методов. Например, при налииие в классе поля mField и опции lombok . accessors . prefix += m , будут сгенерированны методы getField ( ) и setField ( ) .

• lombok . getter . noIsPrefix = true

Переключает префикс имени геттера для boolean переменных с Is на get .

• lombok . toString . includeFieldNames = false

Запрещает вывод названий переменных в сгенерированном toString ( ) методе.

• lombok . toString . doNotUseGetters = true

Запрещает методу toString ( ) пользоваться геттерами, для доступа к данным, и требует прямого доступа к значениям полей.

• lombok . equalsAndHashCode . doNotUseGetters = true

Запрещает методам equals ( ) и hashCode ( ) пользоваться геттерами, для доступа к данным, и требует прямого доступа к значениям полей.

• lombok . anyConstructor . suppressConstructorProperties = true

Запрещает добавление к сгенерированным конструкторам аннотации @ConstructorProperties .

• lombok . singular . useGuava = true

Разрешает использование Immutable из guava, вместо Collections . unmodifiable для @Singular коллекций. Включение этой опции требует наличия guava в classpath.

• lombok . singular . auto = false

Выключает автоматическую генерацию имён методов для добавления одной записи к @Singular коллекции.

• lombok . log . fieldName = идентификатор

Устанавливает имя переменной по умолчанию для логгера.

• lombok . log . fieldIsStatic = false