JEP 198: Light-Weight JSON API

Аннотация

Этот JEP заменён на JEP 540, Simple JSON API (Incubator (инкубационный модуль)).

Предоставить облегчённый API для чтения и создания JSON-документов и потоков данных.

Цели

• Разбор и генерация JSON по RFC7159.

• Функциональность отвечает потребностям Java-разработчиков, работающих с JSON.

• API разбора, позволяющие выбрать одно из представлений JSON-документов и потоков данных: поток токенов разбора, поток событий (включая контекст иерархии документа) или неизменяемое дерево.

• Полезное подмножество API для компактных профилей и Java ME.

• Построение неизменяемого дерева значений с помощью API в стиле Builder.

• API в стиле генератора для вывода потока данных JSON и для «литералов» JSON.

• API преобразования, который принимает на вход существующее дерево значений и возвращает в качестве результата новое дерево значений.

Что не является целью

• Соответствие JSR 353.
• Поддержка в API типобезопасной привязки данных в стиле JAXB.
• API изменения и замены событий.
• API изменения дерева документа.

Мотивация

JSON стал общим языком веб-сервисов, и Java SE пора получить функциональность для работы с JSON-документами и потоками данных. Это предложение призвано предоставить наиболее востребованную функциональность и использовать возможности языка и библиотек Java 8/9.

Описание

Ожидается, что этот JEP будет реализован как набор новых подпакетов в иерархии java.util и будет состоять как минимум из четырёх модулей: события, потоки, деревья, генераторы. Изменять существующие модули, пакеты или классы не предполагается. Не ожидается, что у JSON API будут зависимости, которых ещё нет в базовом модуле Java.

События потока и объекты документа неизменяемы. Неизменяемость позволяет сократить динамический расход памяти, так как экземпляры можно совместно использовать и в потоках, и в деревьях документов. Неизменяемость особенно важна для преобразований деревьев, где бо́льшая часть дерева документа, как правило, не меняется при преобразовании, и очень желательно, чтобы исходное и преобразованное деревья совместно использовали неизменённые части.

Для разбора JSON будут предусмотрены два режима использования: потоки событий и деревья значений. Режим потока событий даст последовательный доступ к токенам разбора или контекстным событиям по мере того, как они по одному разбираются из потока данных (аналогично SAX). Режим дерева значений даст иерархию значений с возможностью навигации, представляющую весь документ (аналогично DOM). Выходные потоки данных JSON можно генерировать либо из деревьев значений, либо напрямую последовательностью отдельных операций (генератор).

API будут поддерживать следующие режимы использования:

• Низкоуровневый push-интерфейс потока токенов разбора для входных потоков данных, поступающих частями.

• Низкоуровневый pull-интерфейс потока токенов разбора для документов и блокирующих источников ввода.

• Низкоуровневый интерфейс java.util.stream для токенов разбора.

• Интерфейс среднего уровня java.util.stream для событий, включающих информацию о структуре документа.

• Pull-интерфейс среднего уровня java.util.stream для сопоставленных событий, аналогичный StAX.

• Неизменяемая иерархия значений (дерево), построенная из потока данных JSON.

• Дерево, построенное с помощью API в стиле Builder.

• API преобразования дерева. Результатом является новое дерево.

• Вывод потока данных JSON из деревьев.

• API в стиле генератора для вывода потока данных JSON и для «литералов» JSON.

Альтернативы

Для Java уже существуют API для JSON. Наиболее популярные из них, как правило, предлагают больше функциональности, чем планируемый API, и/или не используют возможности языка и библиотек Java 8/9.

Тестирование

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