update API section for optional and pruned features #187

kwsutter · 2020-05-22T01:47:13Z

Signed-off-by: Kevin Sutter kwsutter@gmail.com

Changes in this PR...

Created the Jakarta EE 9 ack section (and re-worded the Jakarta EE 8 ack section).
Defined the Proposed Optional, Optional, and Pruned stages of a feature lifecycle.
Attempted to properly allocate all of the various specifications and features according to these lifecycle definitions.
Updated all of the Specification versions in the tables and text for Jakarta EE 9.
Added the missing specifications due to the Java SE adds.
Added the Requirements sub-sections to the end of the API section.
Some general cleanup to make reading and editing easier.

Signed-off-by: Kevin Sutter <kwsutter@gmail.com>

kwsutter · 2020-05-22T01:49:20Z

@dblevins I'm looking for some help with reviewing and updating the sub-section on EJB 4 in the API section of the Platform spec. In the changed files, look for the "TODO" items. I've got questions about the CORBA and Interop changes as well. Thanks!

dblevins

Overall looks good. Will follow up on the list with some of the notes I made. Not using "Request Changes" in the review till we've had some opportunity to discuss.

dblevins · 2020-05-22T17:49:44Z

specification/src/main/asciidoc/platform/ApplicationProgrammingInterface.adoc

 versions, which containers include the technologies, and whether the
 technology is required (REQ), proposed optional (POPT), or optional
 (OPT). Each Jakarta EE profile specification will include a similar table
 describing which technologies are required for the profile. Note that
 some technologies are marked Optional, as described in the next section.

+*Note:* Jakarta EE 9 introduced the concept of "pruned" technologies.


I'll hit the list with this, but I think we should not introduce "prune" as an alias for remove. It would be simpler to promote "remove" as the official term.

Reviewing the discussion on the Platform mailing list, I'm starting to agree. The original spec used "prune" in a different light from how we used "prune" in the release plan. So, maybe it's best to just cut our losses and go with the "remove" terminology and definition. Thanks.l

dblevins · 2020-05-22T18:03:59Z

specification/src/main/asciidoc/platform/ApplicationProgrammingInterface.adoc

+policy to a feature is to allow a gradual deprecation and possible removal
+of the feature from a required component of the platform.
+Product vendors can _choose_ to remove an "optional" feature from their products.
+Product vendors are _required_ to remove a "pruned" feature from their products for


Another topic for the list, but this is likely too restrictive. For example we've removed CORBA but left remote calls as optional. GlassFish and WAS can only support remote calls via CORBA. WAS could remove remote calls entirely, but GlassFish is not capable of doing that as we need at least one Compatible Implementation that supports all optional parts. Therefore there's no way it can both remove CORBA and support the optional remote EJB calls.

There are other reasons that can make this hard. We would likely need some compromise that would allow:

someone to continue to ship a compliant impl of something that may exist as a standalone specification.

the platform to freely add standalone specs to the platform definition (say JCache, NoSQL) and later remove them from the platform definition without "outlawing" its use by the industry in general. There needs to be some way to return to a simple standalone spec status.

Yep, looks like I overstepped the requirement for the "removed" features. I'll remove or reword this statement.

Reworded instead of complete removal of this statement. I want to be clear that "removed" features are no longer maintained. And, that any integration of a "removed" feature with the Platform is left as an exercise for the vendor. That is, it is not defined by the Spec.

I suggest to remove "Product vendors are required to remove a "pruned" feature from their products for" as Product vendors can decide to remove a pruned feature or not.

@Emily-Jiang, thanks. That comment was already addressed in the commits.

dblevins · 2020-05-22T18:05:17Z

specification/src/main/asciidoc/platform/ApplicationProgrammingInterface.adoc


 ===== Java IDL (Proposed Optional)

+*TODO Note:* Since the CORBA module didn't get picked up for Jakarta EE 9, do we remove


We had voted to remove CORBA and that would remove this section.

Thanks for the confirmation! Removed.

dblevins · 2020-05-22T18:10:05Z

specification/src/main/asciidoc/platform/ApplicationProgrammingInterface.adoc

@@ -1015,6 +1060,8 @@ _http://www.omg.org/cgi-bin/doc?formal/2000-06-19_ .

 ===== RMI-JRMP

+*TODO Note:* What to do with this section? Leave as-is, mark Optional, remove?


I think there's a deeper question here because the actual RMI protocol has to my knowledge never been a requirement and I can guarantee is not tested in the TCK. Geronimo never supported the actual RMI protocol and passed EE 4, 5 and 6 full profile TCKs. I don't think even GlassFish supports EJB calls over RMI, just CORBA.

We'll need to continue the discussion you started on the Platform mailing list.

dblevins · 2020-05-22T18:25:17Z

specification/src/main/asciidoc/platform/ApplicationProgrammingInterface.adoc

@@ -1023,6 +1070,9 @@ application component types can be clients of RMI objects.

 ===== RMI-IIOP (Proposed Optional)

+*TODO Note:* Since distributed interop is being removed from the EJB spec, do we remove


I would tentatively say, "yes", but I would need to review the EJB spec's usage of RMI-IIOP.

I know there are specific requirements for non-CORBA protocols that say you must not conflict with RMI-IIOP and I believe the term was "RMI-IIOP compatible." We would want to keep those types of usages because we do have implementations that can only support remote EJBs via CORBA.

Will wait with deleting this section until we complete this discussion on the mailing list.

starksm64 · 2020-05-22T23:02:10Z

specification/src/main/asciidoc/platform/ApplicationProgrammingInterface.adoc

+policy to a feature is to allow a gradual deprecation and possible removal
+of the feature from a required component of the platform.
+Product vendors can _choose_ to remove an "optional" feature from their products.
+Product vendors are _required_ to remove a "pruned" feature from their products for


Drop statement that "Product vendors are required to remove a "pruned" feature from their products for"

+1, thanks!

Reworded instead of complete removal of this statement. I want to be clear that "removed" features are no longer maintained. And, that any integration of a "removed" feature with the Platform is left as an exercise for the vendor. That is, it is not defined by the Spec.

Signed-off-by: Kevin Sutter <kwsutter@gmail.com>

kwsutter · 2020-06-03T12:50:33Z

Asking for a re-review by @dblevins and @starksm64, so that we can make some progress on the Spec for the Milestone release. It doesn't have to be perfect yet, but I think it's much clearer with regards to the optional and removed features. If there are areas that need more attention and we don't have time to address right now, we can just create issues or TODOs for tracking. Thanks!

specification/src/main/asciidoc/platform/ApplicationProgrammingInterface.adoc

Signed-off-by: Kevin Sutter <kwsutter@gmail.com>

kwsutter · 2020-06-10T19:03:11Z

I'm going to go ahead with the merge. Thank you to @ivargrimstad and @kazumura for their approvals. I've marked the sections that still need some work with TODO. It will have to be good enough for the Milestone release and we'll improve on it for the Final release.

update API section for optional and pruned features

a69e89e

Signed-off-by: Kevin Sutter <kwsutter@gmail.com>

kwsutter requested review from dblevins and bshannon May 22, 2020 01:47

dblevins reviewed May 22, 2020

View reviewed changes

starksm64 reviewed May 22, 2020

View reviewed changes

kwsutter added 2 commits May 27, 2020 13:55

rework 'pruned' vs 'removed' usage

2f4e358

Signed-off-by: Kevin Sutter <kwsutter@gmail.com>

forgot some of the commented changes...

31f11fe

Signed-off-by: Kevin Sutter <kwsutter@gmail.com>

kwsutter mentioned this pull request May 28, 2020

Update Jakarta EE Platform and Web Profile Specs per Jakarta EE 9 Release Plan #191

Closed

23 tasks

kwsutter requested review from dblevins and starksm64 June 3, 2020 12:50

kazumura reviewed Jun 3, 2020

View reviewed changes

specification/src/main/asciidoc/platform/ApplicationProgrammingInterface.adoc Show resolved Hide resolved

kwsutter added 2 commits June 5, 2020 09:45

Merge remote-tracking branch 'origin/master' into define-prune

3a5cf40

forgot a 'prune' reference

2ccefa8

Signed-off-by: Kevin Sutter <kwsutter@gmail.com>

kazumura approved these changes Jun 6, 2020

View reviewed changes

ivargrimstad approved these changes Jun 8, 2020

View reviewed changes

kwsutter merged commit 18f2e70 into jakartaee:master Jun 10, 2020

kwsutter deleted the define-prune branch June 10, 2020 19:03

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

update API section for optional and pruned features #187

update API section for optional and pruned features #187

kwsutter commented May 22, 2020

kwsutter commented May 22, 2020

dblevins left a comment

dblevins May 22, 2020

kwsutter May 27, 2020

dblevins May 22, 2020

kwsutter May 27, 2020

kwsutter May 27, 2020

Emily-Jiang Jun 7, 2020

kwsutter Jun 7, 2020

dblevins May 22, 2020

kwsutter May 27, 2020 •

edited

Loading

dblevins May 22, 2020

kwsutter May 27, 2020

dblevins May 22, 2020

kwsutter May 27, 2020

starksm64 May 22, 2020

kwsutter May 27, 2020

kwsutter May 27, 2020

kwsutter commented Jun 3, 2020

kwsutter commented Jun 10, 2020


		===== Java IDL (Proposed Optional)

		TODO Note: Since the CORBA module didn't get picked up for Jakarta EE 9, do we remove

		@@ -1015,6 +1060,8 @@ _http://www.omg.org/cgi-bin/doc?formal/2000-06-19_ .

		===== RMI-JRMP

		TODO Note: What to do with this section? Leave as-is, mark Optional, remove?

		@@ -1023,6 +1070,9 @@ application component types can be clients of RMI objects.

		===== RMI-IIOP (Proposed Optional)

		TODO Note: Since distributed interop is being removed from the EJB spec, do we remove

update API section for optional and pruned features #187

update API section for optional and pruned features #187

Conversation

kwsutter commented May 22, 2020

kwsutter commented May 22, 2020

dblevins left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwsutter May 27, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwsutter commented Jun 3, 2020

kwsutter commented Jun 10, 2020

kwsutter May 27, 2020 •

edited

Loading