Creation and Updates to doc for the new Versionless Features function/feature

hlhoots commented 3 months ago

Feature epic details

For the title of this issue, type: Documentation, Support versionless Jakarta EE/MicroProfile features
Link to development epic: https://github.com/OpenLiberty/open-liberty/issues/25704
Target GA release: 24.0.0.8

Operating systems

Does the documentation apply to all operating systems?

[x] Yes
[ ] No; specify operating systems: __

Summary

Provide a concise summary of your feature. What is the update, why does it matter, and to whom? What do 80% of target users need to know to be most easily productive using your runtime update?

Versionless Features are platform-specific generic features which have no version number and are available for the JakartaEE/JavaEE, and MicroProfile platforms. When you use versionless features, the Open Liberty feature resolver finds the versions of those generic features from the platform specified which are compatible with your other configured features.

Configuration

List any new or changed properties, parameters, elements, attributes, etc. Include default values and configuration examples where relevant:

The <platform> element is new on the <featureManager> element.

<featureManager>
    <platform>microProfile-5.0</platform>
    <feature>mpHealth</feature>
    <feature>mpMetrics</feature>
</featureManager>

Additionally, the PREFFERED_PLATFORM_VERSIONS is a new environment variable.

See more details in the "new" page section below or on the standalone blog post.

Updates to existing topics

To update existing topics, specify a link to the topics that are affected. Include a copy of the current text and the exact text to which it will change. For example: Change ABC to XYZ

Both of the 'server config' pages for OL and WL will have a few sentences that call out versionless features, and point to the new stand alone doc page. Suggestions are as follows:

At this link: https://openliberty.io/docs/latest/reference/config/server-configuration-overview.html

Add a reference to Versionless Features between this bullet and the following paragraph. The link would be the new Versionless Features page down in the later section:

* The autoExpand attribute is set to true so that WAR files are automatically expanded when they are deployed.

**Versionless Features may also be configured in the server.xml.  For more details go <here>**

The term server configuration can be used to refer to all of the files that make up the server configuration or specifically to the configuration that’s in the XML files. If it’s not clear in context, the term server XML configuration might be used to refer to the configuration in the XML files

At this link: https://www.ibm.com/docs/en/was-liberty/core?topic=overview-server-configuration

Features are the units of functionality by which you control the pieces of the runtime environment that are loaded into a particular server. They are the primary mechanism that makes the server composable. The list of features that you specify in the server configuration provides a functional server. See [Liberty features](https://www.ibm.com/docs/en/SSD28V_liberty/com.ibm.websphere.wlp.core.doc/ae/rwlp_feat.html). **Versionless Features may also be configured in the server.xml.  For more details go <here>**

There will also be some updates to the Install documentation

https://openliberty.io/docs/latest/reference/command/featureUtility-commands.html https://www.ibm.com/docs/en/was-liberty/base?topic=liberty-packaging-installing-features

should be updated to say:

Installing versionless features is supported in the featureUtility

Create a new topic

To create a topic, specify a first draft of the topic that you want added and the section in the navigation where the topic should go. With the 24.0.0.8 release, Open Liberty adds a new function called Versionless Features.

Versionless Features are platform-specific generic features which have no version number and are available for the JakartaEE/JavaEE, and MicroProfile platforms. When you use versionless features, the Open Liberty feature resolver finds the versions of those generic features from the platform specified which are compatible with your other configured features.

NOTE: Versionless Features are only supported in server environments, not in client environments.

Versionless features can be specified in three different ways

In the server.xml (best practice) within the element

With the PREFFERED_PLATFORM_VERSIONS environment variable

With a known versioned feature in the server.xml

This example uses the server.xml file and configures the server to do the following things related to Versionless Features:

<featureManager>

    <platform>microProfile-5.0</platform>

    <feature>mpHealth</feature>

    <feature>mpMetrics</feature>

</featureManager>

The platform element configures Open Liberty to support the microProfile-5.0 platform.

The first feature element configures Open Liberty to support the mpHealth feature of the microProfile-5.0 platform.

The second feature element configures Open Liberty to support the mpMetrics feature of the microProfile-5.0 platform.

A similar example utilizing the PREFFERED_PLATFORM_VERSIONS environment variable would be as follows:

PREFFERED_PLATFORM_VERSIONS=microProfile-5.0

NOTE: The PREFFERED_PLATFORM_VERSIONS environment variable can be set in the server.env file (best practice) or via the environment shell.

This server.xml again enables the mpHealth and mpMetrics features specified by the microProfile-5.0 platform from the environment variable:

<featureManager>

    <feature>mpHealth</feature>

    <feature>mpMetrics</feature>

</featureManager>

And lastly, an example using a known versioned feature to resolve versionless features within the server.xml:

<featureManager>

    <feature>mpHealth-3.0</feature>

    <feature>mpMetrics</feature>

    <feature>mpConfig>/feature>

</featureManager>

In the above case, the feature mpHealth is part of MicroProfile-4.0, and no other MicroProfile version, so we can determine the platform version with just this feature. mpMetrics and mpConfig will both resolve to their versions that are part of MicroProfile-4.0. mpMetrics will resolve to mpMetrics-3.0 and mpConfig will resolve to mpConfig-2.0.

The following sections provide more details on configuring Versionless Features and how they work:

Supported platforms and platform versions

Versionless features

Non-versionless features

Server package command

Download packages

Supported platforms and platform versions

The following platforms and versions are supported by Versionless Features in the 24.0.0.8 release:

JakartaEE / JavaEE

javaee-6.0

javaee-7.0

javaee-8.0

jakartaee-9.1

jakartaee-10.0

MicroProfile:

microProfile-1.2

microProfile-1.3

microProfile-1.4

microProfile-2.0

microProfile-2.1

microProfile-2.2

microProfile-3.0

microProfile-3.2

microProfile-3.3

microProfile-4.0

microProfile-4.1

microProfile-5.0

microProfile-6.0

microProfile-6.1

Versionless features

The following versionless features are currently supported as of the 24.0.0.8 release:

JakartaEE / JavaEE versionless features:

appAuthentication / jaspic

appAuthorization / jacc

appClientSupport

appSecurity

batch

beanValidation

cdi

concurrent

connectors / jca

connectorsInboundSecurity / jcainboundsecurity

data

enterpriseBeans / ejb

enterpriseBeansHome / ejbhome

enterpriseBeansLite / ejblite

expressionLanguage / el

enterpriseBeansPersistentTimer / ejbpersistenttimer

enterpriseBeansRemote / ejbremote

faces / jsf

j2eeManagement

mail / javaMail

jdbc

jsonb

jsonp

managedBeans

mdb

messaging / jms

messagingClient / wasjmsclient

messagingSecurity / wasjmssecurity

messagingServer / wasjmsserver

pages / jsp

persistence / jpa

restfulWS / jaxrs

restfulWSClient / jaxrsclient

servlet

websocket

xmlBinding / jaxb

xmlWS / jaxws

MicroProfile versionless features:

mpConfig

mpFaultTolerance

mpHealth

mpJwt

mpMetrics

mpOpenAPI

mpOpenTracing

mpRestClient

mpTelemetry

Non-versionless features

Not all public features are available as versionless features.

For example, because restConnector-2.0 is not clearly associated with either MicroProfile or JakartaEE/JavaEE, there is no restConnector versionless feature. Similarly, springboot features do not have a clear association with an API Platform. No springboot versionless feature exists for springboot-1.5, springboot-2.0, and springboot-3.0.

These features have an association with jakartaee/javaee, but are not available as versionless features:

facesContainer / jsfcontainer

persistenceContainer / jpacontainer

The facesContainer and persistenceContainer enable third party faces and persistence implementations, and are not used unless a third party implementation is being used.

These features are weakly associated with jakartaee/javaee, but are not available as versionless features:

distributedMap

jndi

jpaContainer

json

jwt

monitor

opentracing

persistenceContainer

restConnector

ssl

Server package command

The ‘server package’ command is a command line application that can be utilized by developers to package up their application and all required server related components after development is completed. This is very useful when moving the application to a new environment or moving it to a container image for the Cloud.

As mentioned above the best practice is to use the server.xml to define your Platform selector. If you do utilize the PREFERRED_PLATFORM_VERSIONS environment variable its also a best practice to specify that value in the ‘server.env’ configruation file vs in the actual environment shell. If you utilize the PREFERRED_PLATFORM_VERSIONS variable as a true environment variable in the shell outside of the ‘server.env’ file, and you use the ‘server package’ command the variable will not be retained during packaging.

If this scenario occurs, the ‘server package’ command will issue a warning as follows:

CWWKE0969W: A manual PREFERRED_PLATFORM_VERSION environment variable was specified during server packaging.

In the new environment where the packaged server will be executed, the user would need to re-create the PREFERRED_PLATFORM_VERSION with the same platform values as specified in the prior environment.

Download packages

Versionless Features will be included in the various download packages.

dmuelle commented 3 months ago

Questions-

We say that specifying a platform element is the "best practice", but we can't really use that term as this is a new feature and theres no precedent. We'd be better off explicitly stating the advantage of doing it that way. Same goes for the other two methods- why or why not would you use them? If we're going to document multiple ways of doing the same thing, we need to be clear about why/when you'd choose one vs the other.
In the case where user declares a version by enabling a versioned feature but not platform element- what happens if someone enables versionless features and multiple versioned features from different versions of the same platform? IE should we advise to only enable a single versioned feature as the key for all versionless features in a platform?
Why list "non-versionless" features when none of the listed features are considered part of the supported platforms? ie they are not enabled by our platform convenience features. Do customers know/care about things being "weakly associated" when our config pattern doesn't otherwise reflect that association? Isn't it sufficient to just say the MP/EE features in the table are the only versionless features?
For this warning message: CWWKE0969W: A manual PREFERRED_PLATFORM_VERSION environment variable was specified during server packaging. - should the message also say the variable isnt retained in packaging? It seems unclear what the user is being warned about

dmuelle commented 3 months ago

Hi @hlhoots @rsherget - the initial draft for the versionless features doc is now ready for review:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/versionless-features.html

If any edits are needed, just let me know. When you're satisfied with the draft, you can add the technical reviewed label to this issue to sign off and the doc will publish with the 24.0.0.8 doc release. Thanks!

ramkumar-k-9286 commented 3 months ago

Peer Review

The link text and the actual headers linking them are different. is the change in the link text and the headings fine?

===

To use versionless features, you must declare a corresponding versioned platform. You have three options to declare a platform: ( The heading suggests enabling - also links below mention enabling - so would it not be better to replace 'use' with 'enable'?) -> To enable versionless features, you must declare a corresponding versioned platform. You have three options to declare a platform:

This method is simplest way to configure and keep track of your versionless features. (Acrolinx suggestion) -> This method is the simplest way to configure and track your versionless features.

However, this method might cause problems if you need to package the server by running the server package command. (is can better than might here?) -> However, this method can cause problems if you need to package the server by running the server package command.

When you set PREFERRED_PLATFORM_VERSIONS in the server.env file, the setting is retained by server packaging when you run the server package command. ( Acrolinx - active voice) -> When you set PREFERRED_PLATFORM_VERSIONS in the server.env file, the server packaging retains the setting when you run the server package command.

When you enable at least one versioned feature that is included in only one MicroProfile, Java EE, or Jakarta EE platform version, Open Liberty resolves any versionless features from that platform to their corresponding versions. (Might need to rephrase - acrolinx is picking up multiple issues) "...one versioned feature that is included in only one...." confusing

Features that are not specifically included in the supported platforms are not available in versionless format. (rephrase)

specifically included -> included

For example, because the springBoot-3.0 feature is not specifically included in the MicroProfile, Jakarta EE, or JavaEE platforms, no springBoot versionless feature is available. -> Java EE

dmuelle commented 3 months ago

Thanks for reviewing @ramkumar-k-9286 - all suggestions implemented except:

is can better than might here? I think in this case might works, though either would be correct

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/versionless-features.html

OpenLiberty / docs