«1. Обзор

В этом кратком руководстве показано, как управлять сериализацией и десериализацией перечислений Java с помощью Jackson 2.

Чтобы копнуть немного глубже и узнать о других интересных вещах, которые мы можем сделать в Jackson 2, — вперед. к основному учебнику по Джексону.

2. Управление представлением перечисления

Давайте определим следующее перечисление: 

public enum Distance {
    KILOMETER("km", 1000), 
    MILE("miles", 1609.34),
    METER("meters", 1), 
    INCH("inches", 0.0254),
    CENTIMETER("cm", 0.01), 
    MILLIMETER("mm", 0.001);

    private String unit;
    private final double meters;

    private Distance(String unit, double meters) {
        this.unit = unit;
        this.meters = meters;
    }

    // standard getters and setters
}

3. Сериализация перечислений в JSON

3.1. Представление перечисления по умолчанию

По умолчанию, Джексон будет представлять перечисления Java как простую строку, например: 

new ObjectMapper().writeValueAsString(Distance.MILE);

Результатом будет: 

"MILE"

Что мы хотели бы получить при маршалинге этого перечисления объект JSON должен дать что-то вроде: 

{"unit":"miles","meters":1609.34}

3.2. Перечислить как объект JSON

Начиная с версии Jackson 2.1.2, теперь существует параметр конфигурации, который может обрабатывать такое представление. Это можно сделать с помощью аннотации @JsonFormat на уровне класса: 

@JsonFormat(shape = JsonFormat.Shape.OBJECT)
public enum Distance { ... }

Это приведет к желаемому результату при сериализации этого перечисления для Distance.MILE: 

{"unit":"miles","meters":1609.34}

3.3. Перечисления и @JsonValue

Еще один простой способ управления выводом маршалинга для перечисления — это использование аннотации @JsonValue в геттере: 

public enum Distance { 
    ...
 
    @JsonValue
    public String getMeters() {
        return meters;
    }
}

Здесь мы выражаем то, что getMeters() является фактическим представление этого перечисления. Итак, результатом сериализации будет: 

1609.34

3.4. Пользовательский сериализатор для Enum

До версии Jackson 2.1.2 или если для перечисления требуется еще больше настроек, мы можем использовать собственный сериализатор Jackson. Во-первых, нам нужно определить его: 

public class DistanceSerializer extends StdSerializer {
    
    public DistanceSerializer() {
        super(Distance.class);
    }

    public DistanceSerializer(Class t) {
        super(t);
    }

    public void serialize(
      Distance distance, JsonGenerator generator, SerializerProvider provider) 
      throws IOException, JsonProcessingException {
        generator.writeStartObject();
        generator.writeFieldName("name");
        generator.writeString(distance.name());
        generator.writeFieldName("unit");
        generator.writeString(distance.getUnit());
        generator.writeFieldName("meters");
        generator.writeNumber(distance.getMeters());
        generator.writeEndObject();
    }
}

Теперь мы применим сериализатор к классу, который будет сериализован: 

@JsonSerialize(using = DistanceSerializer.class)
public enum TypeEnum { ... }

Что приводит к: 

{"name":"MILE","unit":"miles","meters":1609.34}

4. Десериализация JSON to Enum

Во-первых, давайте определим класс City, который имеет член Distance: 

public class City {
    
    private Distance distance;
    ...    
}

Далее мы обсудим различные способы десериализации строки JSON в Enum.

4.1. Поведение по умолчанию

По умолчанию Джексон будет использовать имя Enum для десериализации из JSON.

Например, он десериализует JSON: 

{"distance":"KILOMETER"}

В объект Distance.KILOMETER: 

City city = new ObjectMapper().readValue(json, City.class);
assertEquals(Distance.KILOMETER, city.getDistance());

4.2. Использование @JsonValue

Мы узнали, как использовать @JsonValue для сериализации перечислений. Мы можем использовать ту же аннотацию и для десериализации. Это возможно, потому что значения Enum являются константами.

Во-первых, давайте использовать @JsonValue с одним из методов получения — getMeters(): 

public enum Distance {
    ...

    @JsonValue
    public double getMeters() {
        return meters;
    }
}

Теперь возвращаемое значение метода getMeters() представляет объекты Enum. Таким образом, при десериализации примера JSON: 

{"distance":"0.0254"}

Джексон будет искать объект Enum, который имеет возвращаемое значение getMeters() 0,0254. В данном случае это Distance.INCH: 

assertEquals(Distance.INCH, city.getDistance());

4.3. Использование @JsonProperty

Аннотация @JsonProperty используется в экземплярах перечисления: 

public enum Distance {
    @JsonProperty("distance-in-km")
    KILOMETER("km", 1000), 
    @JsonProperty("distance-in-miles")
    MILE("miles", 1609.34);
 
    ...
}

Используя эту аннотацию, мы просто говорим Джексону сопоставить значение @JsonProperty с объектом, аннотированным этим значением.

В результате приведенного выше объявления пример строки JSON: 

{"distance": "distance-in-km"}

Будет сопоставлен с объектом Distance.KILOMETER: 

assertEquals(Distance.KILOMETER, city.getDistance());

4.4. Использование @JsonCreator

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

Рассмотрим представление JSON: 

{
    "distance": {
        "unit":"miles", 
        "meters":1609.34
    }
}

Теперь давайте определим фабричный метод forValues() с аннотацией @JsonCreator: 

public enum Distance {
   
    @JsonCreator
    public static Distance forValues(@JsonProperty("unit") String unit,
      @JsonProperty("meters") double meters) {
        for (Distance distance : Distance.values()) {
            if (
              distance.unit.equals(unit) && Double.compare(distance.meters, meters) == 0) {
                return distance;
            }
        }

        return null;
    }

    ...
}

Обратите внимание на использование аннотации @JsonProperty для привязки полей JSON к аргументы метода.

Затем, когда мы десериализуем образец JSON, мы получим результат: 

assertEquals(Distance.MILE, city.getDistance());

4.5. Использование пользовательского десериализатора

Пользовательский десериализатор можно использовать, если ни один из описанных методов недоступен. Например, у нас может не быть доступа к исходному коду Enum, или мы можем использовать более старую версию Jackson, которая не поддерживает одну или несколько аннотаций, рассмотренных до сих пор.

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

public class CustomEnumDeserializer extends StdDeserializer<Distance> {

    @Override
    public Distance deserialize(JsonParser jsonParser, DeserializationContext ctxt)
      throws IOException, JsonProcessingException {
        JsonNode node = jsonParser.getCodec().readTree(jsonParser);

        String unit = node.get("unit").asText();
        double meters = node.get("meters").asDouble();

        for (Distance distance : Distance.values()) {
           
            if (distance.getUnit().equals(unit) && Double.compare(
              distance.getMeters(), meters) == 0) {
                return distance;
            }
        }

        return null;
    }
}

Затем мы используем аннотацию @JsonDeserialize в Enum для указать наш пользовательский десериализатор: 

@JsonDeserialize(using = CustomEnumDeserializer.class)
public enum Distance {
   ...
}

И наш результат: 

assertEquals(Distance.MILE, city.getDistance());

5. Заключение

«В этой статье показано, как получить лучший контроль над процессами сериализации и десериализации и форматами перечислений Java.

Реализацию всех этих примеров и фрагментов кода можно найти на GitHub.