Перейти к основному содержимому

Создание пользовательской аннотации в Java

· 5 мин. чтения

1. Введение

Аннотации Java — это механизм добавления метаданных в исходный код. Это мощная часть Java, добавленная в JDK5. Аннотации предлагают альтернативу использованию дескрипторов XML и интерфейсов маркеров.

Хотя мы можем прикреплять их к пакетам, классам, интерфейсам, методам и полям, аннотации сами по себе не влияют на выполнение программы.

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

2. Создание пользовательских аннотаций

Мы собираемся создать три пользовательские аннотации с целью сериализации объекта в строку JSON.

Мы будем использовать первый на уровне класса, чтобы указать компилятору, что наш объект может быть сериализован. Затем мы применим второй к полям, которые мы хотим включить в строку JSON.

Наконец, мы будем использовать третью аннотацию на уровне метода, чтобы указать метод, который мы будем использовать для инициализации нашего объекта.

2.1. Пример аннотации уровня класса

Первый шаг к созданию пользовательской аннотации — объявить ее с помощью ключевого слова @interface :

public @interface JsonSerializable {
}

Следующим шагом является добавление мета-аннотаций, чтобы указать область и цель нашей пользовательской аннотации:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.Type)
public @interface JsonSerializable {
}

Как мы видим, наша первая аннотация имеет видимость во время выполнения, и мы можем применить ее к типам (классам) . Более того, у него нет методов, и поэтому он служит простым маркером для маркировки классов, которые можно сериализовать в JSON.

2.2. Пример аннотации уровня поля

Таким же образом мы создаем нашу вторую аннотацию, чтобы отметить поля, которые мы собираемся включить в сгенерированный JSON:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface JsonElement {
public String key() default "";
}

Аннотация объявляет один строковый параметр с именем «ключ» и пустой строкой в качестве значения по умолчанию.

При создании пользовательских аннотаций с методами следует помнить, что эти методы не должны иметь параметров и не могут вызывать исключения . Кроме того, возвращаемые типы ограничены примитивами, String, Class, перечислениями, аннотациями и массивами этих типов, а значение по умолчанию не может быть null .

2.3. Пример аннотации уровня метода

Давайте представим, что перед сериализацией объекта в строку JSON мы хотим выполнить некоторый метод для инициализации объекта. По этой причине мы собираемся создать аннотацию для обозначения этого метода:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Init {
}

Мы объявили общедоступную аннотацию с видимостью во время выполнения, которую мы можем применить к методам наших классов.

2.4. Применение аннотаций

Теперь давайте посмотрим, как мы можем использовать наши пользовательские аннотации. Например, давайте представим, что у нас есть объект типа Person , который мы хотим сериализовать в строку JSON. Этот тип имеет метод, который делает заглавными первую букву имени и фамилии. Мы хотим вызвать этот метод перед сериализацией объекта:

@JsonSerializable
public class Person {

@JsonElement
private String firstName;

@JsonElement
private String lastName;

@JsonElement(key = "personAge")
private String age;

private String address;

@Init
private void initNames() {
this.firstName = this.firstName.substring(0, 1).toUpperCase()
+ this.firstName.substring(1);
this.lastName = this.lastName.substring(0, 1).toUpperCase()
+ this.lastName.substring(1);
}

// Standard getters and setters
}

Используя наши пользовательские аннотации, мы указываем, что можем сериализовать объект Person в строку JSON. Кроме того, выходные данные должны содержать только поля firstName , lastName и age этого объекта. Более того, мы хотим, чтобы метод initNames() вызывался до сериализации.

Установив для ключевого параметра аннотации @JsonElement значение «personAge», мы указываем, что будем использовать это имя в качестве идентификатора поля в выводе JSON.

Ради демонстрации мы сделали initNames() закрытым, поэтому мы не можем инициализировать наш объект, вызывая его вручную, и наши конструкторы также не используют его.

3. Обработка аннотаций

До сих пор мы видели, как создавать собственные аннотации и как использовать их для украшения класса Person . Теперь мы увидим, как воспользоваться ими с помощью Java Reflection API.

Первым шагом будет проверка, является ли наш объект нулевым или нет, а также имеет ли его тип аннотацию @JsonSerializable или нет:

private void checkIfSerializable(Object object) {
if (Objects.isNull(object)) {
throw new JsonSerializationException("The object to serialize is null");
}

Class<?> clazz = object.getClass();
if (!clazz.isAnnotationPresent(JsonSerializable.class)) {
throw new JsonSerializationException("The class "
+ clazz.getSimpleName()
+ " is not annotated with JsonSerializable");
}
}

Затем мы ищем любой метод с аннотацией @Init и выполняем его для инициализации полей нашего объекта:

private void initializeObject(Object object) throws Exception {
Class<?> clazz = object.getClass();
for (Method method : clazz.getDeclaredMethods()) {
if (method.isAnnotationPresent(Init.class)) {
method.setAccessible(true);
method.invoke(object);
}
}
}

Вызов метода . setAccessible ( true) позволяет нам выполнить закрытый метод initNames() .

После инициализации мы перебираем поля нашего объекта, извлекаем ключ и значение элементов JSON и помещаем их в карту. Затем мы создаем строку JSON из карты:

private String getJsonString(Object object) throws Exception {  
Class<?> clazz = object.getClass();
Map<String, String> jsonElementsMap = new HashMap<>();
for (Field field : clazz.getDeclaredFields()) {
field.setAccessible(true);
if (field.isAnnotationPresent(JsonElement.class)) {
jsonElementsMap.put(getKey(field), (String) field.get(object));
}
}

String jsonString = jsonElementsMap.entrySet()
.stream()
.map(entry -> "\"" + entry.getKey() + "\":\""
+ entry.getValue() + "\"")
.collect(Collectors.joining(","));
return "{" + jsonString + "}";
}

Опять же, мы использовали поле . setAccessible ( true ) , потому что поля объекта Person являются закрытыми.

Наш класс сериализатора JSON сочетает в себе все вышеперечисленные шаги:

public class ObjectToJsonConverter {
public String convertToJson(Object object) throws JsonSerializationException {
try {
checkIfSerializable(object);
initializeObject(object);
return getJsonString(object);
} catch (Exception e) {
throw new JsonSerializationException(e.getMessage());
}
}
}

Наконец, мы запускаем модульный тест, чтобы убедиться, что наш объект был сериализован в соответствии с нашими пользовательскими аннотациями:

@Test
public void givenObjectSerializedThenTrueReturned() throws JsonSerializationException {
Person person = new Person("soufiane", "cheouati", "34");
ObjectToJsonConverter serializer = new ObjectToJsonConverter();
String jsonString = serializer.convertToJson(person);
assertEquals(
"{\"personAge\":\"34\",\"firstName\":\"Soufiane\",\"lastName\":\"Cheouati\"}",
jsonString);
}

4. Вывод

В этой статье мы узнали, как создавать различные типы пользовательских аннотаций. Затем мы обсудили, как использовать их для украшения наших объектов. Наконец, мы рассмотрели, как их обрабатывать с помощью Java Reflection API.

Как всегда, полный код доступен на GitHub .