Статья

Введение в Jackson JSON ObjectMapper в Java

Эта статья посвящена пониманию класса Jackson ObjectMapper и тому, как сериализовать объекты Java в JSON и десериализовать строку JSON в объекты Java.

Зависимости

Давайте сначала добавим следующие зависимости в pom.xml:
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.13.4.2</version>
</dependency>
Эта зависимость также автоматически добавит следующие библиотеки в classpath:
  • jackson-annotations
  • jackson-core

Чтение и запись с помощью ObjectMapper

Давайте начнем с основных операций чтения и записи.
Простой метод readValue ObjectMapper является хорошей отправной точкой. Мы можем использовать его для синтаксического анализа или десериализации содержимого JSON в объект Java.
Кроме того, мы можем использовать метод writeValue для сериализации любого объекта Java в формат JSON.
В этой статье мы будем использовать следующий класс Cat в качестве объекта для сериализации или десериализации:
public class Cat {
    private String name;
    private String color;
}

Java объект в JSON

Давайте рассмотрим первый пример сериализации объекта Java в JSON с использованием метода writeValue класса ObjectMapper:
ObjectMapper objectMapper = new ObjectMapper();
Cat cat = new Cat("Barsik", "Black");
objectMapper.writeValue(new File("cat.json"), cat);
Результатом будет файл со следующим содержимым:
{
    "name":"Barsik", 
    "color":"black"
}
Методы writeValueAsString и writeValueAsBytes класса ObjectMapper генерируют JSON из объекта Java и возвращают сгенерированный JSON в виде строки или массива байтов:
String catAsString = objectMapper.writeValueAsString(cat);

JSON в объект Java

Ниже приведен простой пример преобразования строки JSON в объект Java с использованием класса ObjectMapper:
String json = "{ \"color\" : \"Black\", \"name\" : \"Barsik\" }";
Cat cat = objectMapper.readValue(json, Cat.class);	
Метод readValue() также может принимать другие входные данные, например файл, содержащий строку JSON, или URL:
Cat cat1 = objectMapper.readValue(new File("json_cat.json"), Cat.class);

Cat cat2 = objectMapper.readValue(new URL("http://test.com/json_cat.json"), Cat.class);

JSON в Jackson JsonNode

Также JSON может быть преобразован в объект JsonNode и использован для извлечения данных из определенного узла:
String json = "{ \"color\" : \"Black\", \"name\" : \"Barsik\" }";
JsonNode jsonNode = objectMapper.readTree(json);
String color = jsonNode.get("color").asText();

// результат: color -> Black

Создание List из строки JSON Array

Мы можем разобрать массив объектов JSON в список объектов Java, следующим образом:
String jsonCatArray = 
  "[{ \"color\" : \"Black\", \"name\" : \"Barsik\" }, { \"color\" : \"White\", \"name\" : \"Vasya\" }]";
List<Cat> listCat = objectMapper.readValue(jsonCatArray, new TypeReference<List<Cat>>(){});

Создание Map из JSON

String json = "{ \"color\" : \"Black\", \"name\" : \"Barsik\" }";
Map<String, Object> map 
  = objectMapper.readValue(json, new TypeReference<Map<String,Object>>(){});

Расширенные функции

Одной из самых сильных сторон библиотеки Jackson является настраиваемый процесс сериализации и десериализации.
При преобразовании объектов JSON в классы Java, в случае, если строка JSON содержит некоторые новые поля, обработка по умолчанию приведет к исключению:
String jsonString 
  = "{ \"color\" : \"Black\", \"name\" : \"Barsik\", \"age\" : \"5\" }";
Строка JSON в приведенном выше примере в процессе синтаксического анализа для класса Cat приведет к исключению UnrecognizedPropertyException.

С помощью метода configure мы можем расширить действия по умолчанию, чтобы игнорировать новые поля:
objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
Cat cat = objectMapper.readValue(jsonString, Cat.class);

JsonNode jsonNodeRoot = objectMapper.readTree(jsonString);
JsonNode jsonNodeAge = jsonNodeRoot.get("age");
String age = jsonNodeAge.asText();
Еще один вариант основан на FAIL_ON_NULL_FOR_PRIMITIVES, который определяет, разрешены ли null значения для примитивных типов:
objectMapper.configure(DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES, false);
Аналогично, FAIL_ON_NUMBERS_FOR_ENUM определяет, разрешено ли сериализовать/десериализовать значения перечислений (enum) в виде чисел:
objectMapper.configure(DeserializationFeature.FAIL_ON_NUMBERS_FOR_ENUMS, false);

Создание собственного сериализатора или десериализатора

Другой важной особенностью класса ObjectMapper является возможность регистрации пользовательского сериализатора и десериализатора.
Пользовательские сериализаторы и десериализаторы очень полезны в ситуациях, когда входной или выходной JSON отличается по структуре от класса Java, в который он должен быть сериализован или десериализован.
Ниже приведен пример сериализатора JSON:
public class CustomCatSerializer extends StdSerializer<Cat> {
    
    public CustomCatSerializer() {
        this(null);
    }

    public CustomCatSerializer(Class<Cat> t) {
        super(t);
    }

    @Override
    public void serialize(
      Cat cat, JsonGenerator jsonGenerator, SerializerProvider serializer) {
        jsonGenerator.writeStartObject();
        jsonGenerator.writeStringField("name", cat.getName());
        jsonGenerator.writeStringField("cat_breed", "Scottish Fold");
        jsonGenerator.writeEndObject();
    }
}
Этот пользовательский сериализатор может быть вызван следующим образом:
ObjectMapper mapper = new ObjectMapper();
SimpleModule module = 
  new SimpleModule("CustomCatSerializer", new Version(1, 0, 0, null, null, null));
module.addSerializer(Cat.class, new CustomCatSerializer());
mapper.registerModule(module);
Cat cat = new Cat("white", "Vasya");
String catJson = mapper.writeValueAsString(cat);
Вот как выглядит cat (в виде JSON) на стороне клиента:
var carJson = {"name":"Vasya","cat_breed":"Scottish Fold"}
А это пример пользовательского JSON десериализатора:
public class CustomCatDeserializer extends StdDeserializer<Cat> {
    
    public CustomCatDeserializer() {
        this(null);
    }

    public CustomCatDeserializer(Class<?> vc) {
        super(vc);
    }

    @Override
    public Cat deserialize(JsonParser parser, DeserializationContext deserializer) {
        Cat cat = new Cat();
        ObjectCodec codec = parser.getCodec();
        JsonNode node = codec.readTree(parser);
        
        // try catch block
        JsonNode colorNode = node.get("color");
        String color = colorNode.asText();
        cat.setColor(color);
        return cat;
    }
}
Этот пользовательский десериализатор может быть вызван таким образом:
String json = "{ \"color\" : \"Black\", \"name\" : \"Barsik\" }";
ObjectMapper mapper = new ObjectMapper();
SimpleModule module =
  new SimpleModule("CustomCatDeserializer", new Version(1, 0, 0, null, null, null));
module.addDeserializer(Cat.class, new CustomCatDeserializer());
mapper.registerModule(module);
Cat cat = mapper.readValue(json, Cat.class);

Работа с датами

Сериализация Java.util.Date по умолчанию выдает число, то есть временную метку (timestamp) эпохи (количество миллисекунд с 1 января 1970 года по UTC). Но это не очень удобочитаемо для человека и требует дальнейшего преобразования для отображения в удобочитаемом формате.
Давайте напишем класс со свойством birthday:
public class Student 
{
    private String name;
    private Date birthday;

    // getters setters...
}
Чтобы изменить строковый формат даты в JSON, к примеру на “yyyy-MM-dd HH:mm a z“, рассмотрим следующий фрагмент кода:
ObjectMapper objectMapper = new ObjectMapper();
DateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm a z");
objectMapper.setDateFormat(df);
String studentAsString = objectMapper.writeValueAsString(student);
// результат: {"name":"John", "birthday":"2001-06-18 15:44 AM CEST"}

Работа с коллекциями JSON

Еще одна небольшая, но полезная функция, доступная через класс DeserializationFeature, – это возможность генерировать нужный нам тип коллекции из массива JSON.
Примеры:
String jsonCatArray = 
  "[{ \"color\" : \"Black\", \"name\" : \"Barsik\" }, { \"color\" : \"White\", \"name\" : \"Vasya\" }]";
ObjectMapper objectMapper = new ObjectMapper();
objectMapper.configure(DeserializationFeature.USE_JAVA_ARRAY_FOR_JSON_ARRAY, true);

Cat[] cats = objectMapper.readValue(jsonCatArray, Cat[].class);

List<Cat> listCat = objectMapper.readValue(jsonCatArray, new TypeReference<List<Cat>>(){});

Заключение

Jackson – это надежная и зрелая библиотека сериализации / десериализации JSON для Java. ObjectMapper API предоставляет простой и гибкий способ анализа и генерации объектов JSON. В этой статье обсуждались основные функции, которые делают библиотеку такой популярной.
java