jakartaee-platform
jakartaee-platform copied to clipboard
eclipse-ee4j
Look to deprecate JNDI, @Resource, @Resources in favor of Config
Is your feature request related to a problem? Please describe. The JNDI namespace and @Resource/@Resources common annotations are mechanisms for accessing environment details that currently require populating based on default rules and/or implementation specification configuration mechanisms. These will be essentially obsolete with the introduction of the Jakarta Config specification.
Describe the solution you'd like The Jakarta Config specification should take ownership of configuration and injection of the standard resource types available in Jakarta and JNDI and @Resource/@Resources common annotations marked for depreciation for future removal. In the interim, how to configure these deprecated elements should be defined in the Jakarta Config spec.
Describe alternatives you've considered None.
Additional context None.
For EE11 we do not have Config, so the process would simply be to deprecate now in preparation for replacement in a future release.
@edburns from the https://jakarta.ee/committees/specification/versioning/ process, we need to make a statement on the deprecation of @Resource and @Resources on the common-annotations feature, ideally with @Deprecation on the API/javadoc which probably requires a minor release, and in the platform spec. JNDI is just a platform feature so it just needs to be deprecated there.
Deprecation
API methods that are marked for deprecation should be annotated with @Deprecated, and where possible the JavaDoc for the method should be updated to point users towards the replacement (if there is one). This mandates a minor version increment.
As noted above, the “deprecation” of behaviour by changing it to something else can happen in two ways:
- Using a flag to switch from the old to the new behaviour in a minor release. The flag and support for the old behaviour can be dropped in a later major release
- Without using a flag to switch between the old and new behaviour in a major release. This should be avoided where possible to avoid sudden breaking changes.
Component features must be “deprecated” via a process similar to the Pruning process that existed before. A mandatory Component Feature is transitioned to being an optional feature in release N of the Component specification, and the optional feature should be marked as “Deprecated” in some manner (for example in a “Proposed for Removal” section of the specification). The optional feature may then be removed from the Component specification in release N+1 (or beyond). As noted above, the transition of the feature to being optional would mandate a major release, and the removal of it would mandate a subsequent major release.
An existing optional feature which has not yet been marked for deprecation must be marked as deprecated in a minor or major release, to then be removed in a subsequent major release.
It should be stressed that optional features do not have to be removed – the Component specification can maintain them as optional for as long as desired.
See the Platform Feature section for more details on how Component Features which are pruned in this manner are dealt with there.
Deprecation from a Platform specification stance has two scopes:
- Removal of Component specifications
- Removal of Component features
Component Features
When a Component feature is transitioned from being mandatory to optional, the Platform specification and its profiles must include a version of the specification which maintains this change for at least one release. Before an optional feature can be removed from the Platform specification, it must be marked for at least one release under a “Proposed for Removal” section. When removing an optional feature from the Platform specification or its profiles a reference must be provided to the version of the specification that marked the feature as “Proposed for Removal”.
It should be noted that the Platform specification and its profiles are not allowed to “jump” a release to introduce breaking changes without applying for an exception This is to discourage a component specification quickly doing two or more back-to-back releases to quickly remove a feature.
The intent is that there must be a release of the Platform specification which contains the feature in a “Proposed for Removal” state before it can be removed, but this should not necessarily prevent a component specification from moving at a quicker pace than that of the Platform.
For an example scenario:
- A Component specification defines a mandatory feature in release 2.0 and this is included in the Platform specification release X.
- The Component specification transitions the feature to being an optional one in release 3.0 and marks it for removal.
- The Component specification removes the feature entirely in release 4.0.
- Platform specification release X+1 must contain Component specification 3.0, mark the optional Component feature as included, and can also mark the optional Component feature under the “Proposed for Removal” section – it is not allowed to immediately include Component specification 4.0 since this would bypass the “Proposed for Removal” step.
- Platform specification release X+2 can proceed to include version 4.0 of the Component specification with the feature removed. Alternatively, the Platform specification release X+2 may choose to maintain Component specification 3.0, but would not have to include the optional feature if it did not want to.
Isn't this something that would be done in EE 12? The general spirit of what I read above is in release N you provide an alternative for a use case and declare the original solution as optional and deprecated. And then in N+1 you can remove. But we don't have the alternative. We'd basically be telling our users that in the future they'll have a significant migration task, but with no way for them to get started on that migration. A reasonable reaction to that would be to move off of EE.
It does not need to be done in EE 12, that would simply be the first time it could be removed if deprecated in EE 11. The other issue is that removal does not mean it cannot be supported. The main goal should be driving the baseline to have minimal requirements. JNDI is not a minimal requirement and is not a very type safe, portable thing to conrfigure.
No one likes thinking about labelling technologies as legacy, but that is the reality. We probably should have a legacy profile that includes dropped specification and TCK tests for vendors to support on top of their more modern cores.
We probably should have a legacy profile
The idea of the legacy profile came up a long time ago already, but we never acted on it.
The legacy idea is interesting. Up through EE 9, things EE removed were mostly little used or long since replaced. But starting with 10 we're starting to remove things the people are still using.
