JEP 179: Document JDK API Support and Stability

Аннотация

В JDK давно есть недостаток: для типов com.sun.* и других типов, которые поставляются с JDK, но не входят в спецификацию Java SE, чётко не определён контракт использования с точки зрения поддержки и стабильности. Эти контракты и возможные правила развития должны быть чётко зафиксированы как в исходном коде типов, так и в получаемых class-файлах. Эту информацию можно смоделировать с помощью типов аннотаций, специфичных для JDK.

Цели

Основные цели этого предложения — зафиксировать результаты исследований статуса этих API, проведённых перед модуляризацией, и сделать эту информацию понятнее для тех, кто сопровождает JDK, и для разработчиков, использующих JDK.

Также может быть полезно помечать API как доступный для использования определёнными сторонами, но не для общего использования.

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

Ожидается, что механизмом хранения информации о статусе API будут один или несколько типов аннотаций со вспомогательными типами для моделирования, например перечислениями. Эти типы предназначены для использования в JDK. Если они окажутся полезны и за пределами JDK, это будет удачным результатом, но, например, разработка очень универсальной схемы классификации с очень тонкой градацией уровней стабильности выходит за рамки этой работы.

Мотивация

Помимо реализации API Java SE, кодовая база JDK содержит исходный код других API, не входящих в спецификацию Java SE и находящихся в других пространствах имён, и дистрибутивы JDK поставляются с этими API. Некоторые из этих API JDK развиваются по тем же общим правилам, что и API Java SE: они пригодны для разработки общего назначения, поддерживаются поставщиком JDK, стабильны и развиваются в основном совместимым образом. Другие API, включённые в JDK, предназначены только для использования в самой реализации JDK, и третьим сторонам не следует на них полагаться. Пространство имён com.sun.*, используемое JDK, содержит смесь таких «поддерживаемых» и «неподдерживаемых» API. Этот JEP предлагает записывать информацию о поддерживаемости и связанных с ней свойствах в исходном коде соответствующих типов и пакетов. Запись этой информации сделает статус API понятнее и явнее, в том числе в генерируемой документации javadoc, а также позволит инструментам программно проверять, нет ли недопустимого использования. Запись этой информации должна потребовать небольших дополнительных усилий сверх подготовки к модульности, которая уже ведётся для JDK 8 в рамках JEP 162.

Описание

Аннотации и вспомогательные типы, с помощью которых документируется статус соответствующих API, будут находиться в пространстве имён jdk.*. Иными словами, эти типы будут частью JDK, а не Java SE. Ожидается, что, помимо новых типов, добавленных в сам jdk.*, аннотации будут использоваться в основном для типов в унаследованном пространстве имён com.sun.*. Ожидается, что до определения окончательного набора различий между API потребуются некоторые исследования и эксперименты. Первоначальный тип аннотации jdk.Supported, который уже был добавлен в JDK 8 для пробного использования, допускает булеву классификацию «поддерживается / не поддерживается». Другие возможные интересующие классификации включают JRE и JDK, поддержку за пределами JDK только для определённых пользователей или групп, а также градации стабильности и правил развития.

Следуя принципу don't-repeat-yourself («не повторяйся»), в конечном счёте сборку JDK следует изменить так, чтобы информация прото-модульной системы ct.sym формировалась из аннотаций в исходном коде, а не за счёт неочевидной зависимости от makefile документации, но такой рефакторинг сборки не является строго обязательной частью этой работы.

Риски и допущения

Если аннотации этой возможности изначально будут спроектированы так, чтобы фиксировать только какое-либо значение «да/нет» в виде булева значения, а в будущем понадобится больше классификаций, развивать исходный тип (или типы) для моделирования новой схемы может оказаться неудобно. Поэтому в JDK 8 следует тщательно определить устойчивый набор различий.

Зависимости

Эта возможность основана на исследованиях, проведённых для JEP 162, Prepare for Modularization.

Влияние

• Другие компоненты JDK: понятия, используемые для аннотаций из этого предложения, могут помочь формализовать правила в других частях JDK, но основная цель работы — помочь в управлении API, не входящими в Java SE.

• Совместимость: эта возможность позволит лучше документировать правила совместимости и следить за их соблюдением.

• Документация: новые аннотации будут @Documented и поэтому будут включены во все генерируемые комплекты документации javadoc.

• TCK: поскольку это предложение находится за пределами Java SE, на TCK оно не влияет.