JEP 11: Incubator Modules

Аннотация

Модули Incubator (инкубационный модуль) — это способ передать в руки разработчиков неокончательные API и неокончательные инструменты, пока эти API и инструменты движутся либо к окончательному утверждению, либо к удалению в одном из будущих выпусков.

Цели

• Дать JDK Release Projects возможность распространять ограниченный набор API и инструментов, которые ещё не окончательны и не завершены и для которых будут полезны отзывы разработчиков или пользователей. Это снизит вероятность дорогостоящих ошибок в платформе Java SE и в JDK.

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

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

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

• Цель не в том, чтобы каждая возможность, разрабатываемая для JDK, на каком-то этапе своего жизненного цикла находилась в статусе Incubator (хотя это может быть желательно).

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

Мотивация

Многим API платформы Java SE, поддерживаемым API JDK или широко полезным инструментам JDK пошло бы на пользу провести некоторое время в JDK Release Project до стандартизации в JCP или до того, как их иным образом признают стабильными. Нахождение в JDK Release Project, а значит, и в производных бинарных сборках, например на jdk.java.net, упрощает использование новой возможности заинтересованным сторонам за пределами непосредственного сообщества OpenJDK. Опыт, полученный и переданный по обычным каналам, таким как блоги, рассылки, программы взаимодействия с сообществом и конференции, затем можно учесть до того, как возможность будет окончательно утверждена или же удалена в одном из будущих Release Project.

Описание

Incubator-возможность — это API или инструмент нетривиального размера, который разрабатывается для последующего включения в платформу Java SE или в JDK. API или инструмент ещё недостаточно проверен, поэтому желательно отложить стандартизацию или окончательное утверждение на небольшое число выпусков Feature Release (функциональный выпуск), чтобы получить дополнительный опыт и отзывы.

Incubator-модуль — это модуль в JDK Release Project, который предоставляет Incubator-возможность: модуль либо экспортирует Incubator-API, либо содержит Incubator-инструмент, либо и то и другое.

Incubator-модуль определяется по префиксу jdk.incubator. в имени модуля, независимо от того, экспортирует ли модуль Incubator-API или содержит Incubator-инструмент.

Incubator-API определяется по префиксу jdk.incubator. в именах экспортируемых пакетов. Incubator-API экспортируется только Incubator-модулем.

Incubator-инструмент может использовать префикс jdk.incubator в имени, под которым он вызывается из командной строки, но это не обязательно.

Если Incubator-API будет стандартизирован в платформе Java SE или иным образом переведён в какой-либо стабильный статус в JDK, то его пакеты будут переименованы и затем экспортированы из модуля, не являющегося Incubator-модулем. Тем, кто начал использовать API рано, придётся как минимум изменить свои инструкции import, а если API изменится существеннее, может понадобиться переработать код, который его использует. Аналогично, если Incubator-инструмент будет переведён в какой-либо стабильный статус, тем, кто начал использовать его рано, может понадобиться изменить скрипты, которые его вызывают, чтобы учесть изменения в функциональности и интерфейсе командной строки инструмента.

Если Incubator-API не будет стандартизирован или иным образом переведён в стабильный статус через небольшое число выпусков JDK Feature Release, то он больше не сможет оставаться в статусе Incubator, и его пакеты и Incubator-модуль будут удалены. Аналогично, если Incubator-инструмент не будет переведён в стабильный статус, его Incubator-модуль будет удалён.

Процесс и развитие

Incubator-возможность (API или инструмент) использует процесс JEP в неизменном виде со следующими рекомендациями:

1. В JEP, определяющем возможность, должно быть ясно указано, что запланирован статус Incubator и что результатом выполнения JEP станет Incubator-модуль, который экспортирует API или содержит инструмент.

2. Для Incubator-возможности, вместе с любыми эволюционными изменениями API, которая позже переводится в платформу Java SE или в какой-либо другой стабильный статус в JDK, должен быть создан новый JEP, который предлагает и документирует это изменение. В новом JEP допускается, но не требуется, поставлять переведённый в стабильный статус API или инструмент в отдельном модуле; API или инструмент может быть встроен в существующий стандартный модуль или в модуль JDK, не являющийся Incubator-модулем.

3. Если Incubator-возможность позже удаляется, новый JEP не нужен. Incubator-модуль, содержащий Incubator-возможность, может быть удалён без объявления. Рекомендуется обновить исходный JEP, чтобы зафиксировать судьбу возможности.

Один Incubator-модуль должен содержать одну Incubator-возможность. (Если Incubator-инструмент связан с API, этот API может считаться частью инструмента и экспортироваться Incubator-модулем, который содержит Incubator-инструмент.) Выделение отдельного Incubator-модуля для каждой Incubator-возможности поможет избежать появления «разнородного» Incubator-модуля, который превращается в свалку, как это случалось в прошлом в некоторых частях устаревшего пространства имён sun.*. У Incubator-возможностей есть явный владелец, и ясно, какое будущее их ждёт или не ждёт.

Incubator-возможность не обязательно сохраняется навсегда в JDK Release Project, в котором она появилась, или в каждом выпуске производных бинарных сборок, полученных из этого Release Project. Например, Incubator-возможность может измениться или даже быть удалена между разными выпусками обновлений JDK Release Project. Кроме этого явного указания на то, когда допускаются изменения, данное предложение намеренно не даёт никаких дальнейших рекомендаций. Такие решения лучше оставить на усмотрение владельца конкретной возможности.

Incubator-модуль и его API или инструмент не останутся в JDK надолго, поэтому в каком-то смысле они с самого рождения окончательно устаревшие. Однако правильнее считать статус Incubator и устаревание совершенно отдельными понятиями, поэтому аннотацию @Deprecated и тег JavaDoc @deprecated не следует использовать в Incubator-модулях или их API.

Связь с другими модулями

Incubator-модули должны экспортировать только Incubator-API, т. е. пакеты в пространстве имён jdk.incubator. Следовательно:

• Incubator-модули не должны экспортировать API в пространствах имён java. или javax., которые находятся в ведении JCP. Этим Incubator-модули отличаются от стандартных модулей, таких как java.base.

• Incubator-модули не должны экспортировать поддерживаемые API JDK. Этим Incubator-модули отличаются от модулей JDK, таких как jdk.compiler, которые экспортируют такие API.

• Incubator-модули не должны экспортировать критически важные внутренние API. Incubator-модули никак не связаны с модулем jdk.unsupported.

Стандартные модули и модули JDK, не являющиеся Incubator-модулями, не должны объявлять зависимости requires transitive от Incubator-модулей или иным образом открывать в своих экспортируемых API типы, экспортируемые из Incubator-модулей. В исключительных случаях стандартным модулям и модулям JDK, не являющимся Incubator-модулями, может быть допустимо объявлять зависимости requires (а не requires transitive) от Incubator-модулей.

Incubator-модули могут объявлять зависимости requires или requires transitive от других Incubator-модулей.

Incubator-модули входят в образ среды выполнения JDK, который создаётся стандартной сборкой JDK. Однако по умолчанию Incubator-модули не разрешаются для приложений в пути классов. Кроме того, по умолчанию Incubator-модули не участвуют в связывании сервисов для приложений в пути классов или в пути модулей.

Приложения в пути классов должны использовать параметр командной строки --add-modules, чтобы запросить разрешение Incubator-модуля. Приложения, разработанные как модули, могут объявлять зависимости requires или requires transitive от Incubator-модуля напрямую. (Некоторые Incubator-модули, например предоставляющие инструменты командной строки, могут вообще не экспортировать пакеты, а вместо этого предоставлять реализации сервисов, чтобы к инструментам можно было обращаться программно. Обычно не рекомендуется объявлять зависимость от модуля, который не экспортирует пакетов, но в этом случае это необходимо, чтобы Incubator-модуль был разрешён, а его поставщики сервисов участвовали в связывании сервисов.)

Во время сборки JDK Incubator-модули должны упаковываться в файлы jmod с параметром --do-not-resolve-by-default инструмента jmod, чтобы они не входили в набор корневых модулей по умолчанию для безымянного модуля. Фактически это делает их подключаемыми только по явному выбору («opt-in»). Кроме того, инструменту jmod должен передаваться параметр --warn-if-resolved=incubating, чтобы при разрешении Incubator-модуля выдавалось предупреждение во время компиляции, компоновки и выполнения. Это предупреждение можно подавить во время компиляции, но не в остальных случаях.

Incubator-модулям по умолчанию не предоставляются никакие разрешения безопасности.

Incubator-модули могут зависеть от операционной системы.

Точки интеграции

Многие новые API должны интегрироваться с API java.* и javax.* платформы Java SE, но в статусе Incubator API должен находиться в пространстве имён jdk.incubator. и поэтому «стоит особняком» от API SE. Например, рассмотрим Streams API: для него могло бы понадобиться, чтобы условный класс jdk.incubator.stream.Streams предоставлял статические фабричные методы, такие как fromList, fromSet и т. д., чтобы обеспечить интеграцию с существующим Collections API. Хотя это компромисс, точки интеграции с существующими API SE обычно составляют сравнительно небольшую часть нового API.

В некоторых случаях Incubator-возможность может быть тесно интегрирована со средой выполнения Java и с JVM. В таких случаях низкоуровневые операции можно открыть через квалифицированный экспорт из соответствующих модулей JDK в Incubator-модуль, содержащий эту возможность. Incubator-модуль, у которого есть хотя бы один квалифицированный экспорт из модуля JDK, должен быть тесно связан с ним, т. е. его хэш должен быть записан в экспортирующем модуле, и поэтому такой Incubator-модуль нельзя обновить отдельно. Incubator-модуль, у которого нет квалифицированных экспортов из модулей JDK, не обязан быть тесно связан и поэтому может допускать отдельное обновление. Если в JVM нужна базовая поддержка статуса Incubator, может понадобиться предусмотреть аргумент командной строки, например -XX:+UnlockExperimentalVMOptions, или же сделать так, чтобы такая поддержка включалась автоматически при наличии Incubator-модуля.

Документация

JavaDoc Incubator-API собирается в рамках сборки документации JDK так же, как для других API JDK. Будет добавлена дополнительная структура каталогов jdk/incubator/, чтобы сгруппировать документацию Incubator-возможностей по модулям. Весь JavaDoc, собранный для Incubator-API, будет содержать явные, заметные и единообразные предупреждения о том, что возможность находится в статусе Incubator, и предостережение о том, что со временем возможность будет удалена.

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

Многие новые возможности тесно интегрированы со средой выполнения Java и с JVM. Поэтому распространять их независимо от JDK было бы сложно, если не невозможно, так как они должны быть жёстко привязаны к конкретной сборке конкретного выпуска. Распространение вместе с JDK гарантирует, что все необходимые части тесно связаны между собой.

Двоичные сборки Early Access (ранний доступ), или EA, проекта JDK Release Project или другого проекта по-прежнему будут предлагаться, чтобы разработчики могли опробовать новые возможности и оставить отзывы до выпуска General Availability (общедоступный выпуск), или GA. Однако число загрузок EA исторически было намного меньше, чем загрузок GA, потому что большинство разработчиков предпочитают более высокий уровень стабильности и качества, который обеспечивают выпуски GA. Поэтому выпуски EA привлекают лишь ограниченное внимание и дают лишь ограниченную обратную связь, тогда как Incubator-возможности рассчитаны на широкий круг разработчиков и потому нуждаются в широком внимании и обильной обратной связи. Из-за этого выпуск возможности в EA не может полноценно заменить выпуск Incubator-возможности в GA.

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

Код, из которого состоит Incubator-возможность, должен тестироваться так же, как любой другой код в JDK. Конкретные требования к тестированию возможности должны быть описаны в JEP, который вводит эту Incubator-возможность.

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

Очевидный риск Incubator-возможности состоит в том, что чей-то код или скрипт станет от неё зависеть и затем окажется «сломан» при запуске в более позднем выпуске, из которого модуль этой Incubator-возможности удалён. Этот риск снижается за счёт того, что Incubator-возможности включаются только явно (opt-in), то есть Incubator-модули по умолчанию не разрешаются, а при разрешении Incubator-модулей на всех этапах выдаются предупреждения.