API to expose specification versions

[dblevins]

We're beginning to make more backwards incompatible changes to APIs and behavior, which is a totally fine evolution of the platform.

I think this means we owe it to users to allow them to reliably and portably determine which exact specification version the application might be running in so they can act accordingly. A great deal of people write libraries that are used in multiple applications and those applications typically span a few Jakarta EE versions. There really needs to be an easy API an application can make use of to tell them what spec version they're running in.

Before we get into proposals, what do you think about the goal?

In terms of proposals, we could do JNDI calls, system properties, etc. The JVM takes the system property approach. We could possibly do the same using the short names of each spec. I.e. something like:

• jakarta.platform.version = 10.0
• jakarta.core.version = 10.0
• jakarta.servlet.version = 6.0
• jakarta.pages.version = 3.1
• jakarta.batch.version = 2.1
  ...
  etc

FYI all the short names are used in both these places:

• https://jakarta.ee/specifications/pages/
• https://github.com/jakartaee/pages/

The version would be just major+minor, no patch or service versions. The TCK of each spec would look for the system properties that relate to their spec. In whole, there would need to be a system property present for each spec the server implements. People would not only be able to use the system property to know what version is supported, but if there is support at all. For example, is MVC in the server? This is all information application developers can use to determine in code what kind of behavior they have.

[scottmarlow]

On 9/28/23 7:21 PM, David Blevins wrote: We're beginning to make more backwards incompatible changes to APIs and behavior, which is a totally fine evolution of the platform. I think this means we owe it to users to allow them to reliably and portably determine which exact specification version the application might be running in so they can act accordingly. A great deal of people write libraries that are used in multiple applications and those applications typically span a few Jakarta EE versions. There really needs to be an easy API an application can make use of to tell them what spec version they're running in. Before we get into proposals, what do you think about the goal? In terms of proposals, we could do JNDI calls, system properties, etc. The JVM takes the system property approach. We could possibly do the same using the short names of each spec. I.e. something like: - jakarta.platform.version = 10.0 - jakarta.core.version = 10.0 - jakarta.servlet.version = 6.0 - jakarta.pages.version = 3.1 - jakarta.batch.version = 2.1 ... etc FYI all the short names are used in both these places: - https://jakarta.ee/specifications/pages/ - https://github.com/jakartaee/pages/ The version would be just major+minor, no patch or service versions. The TCK of each spec would look for the system properties that relate to their spec. In whole, there would need to be a system property present for each spec the server implements. People would not only be able to use the system property to know what version is supported, but if there is support at all. For example, is MVC in the server? This is all information application developers can use to determine in code what kind of behavior they have. +1 for this great point David! Thanks for raising it! Using a Jakarta EE Server information class could offer more flexibility than using (global) system properties as the SPEC API versions may vary for different EE deployments (e.g. they might exclude certain SPEC APIs from their classpath and instead package a different version of the SPEC API or something like that). There are some use cases where deployment libraries might detect that certain SPEC APIs are absent or a different version. In response to detecting a different version or absent SPEC API, the library may want to throw exceptions or use some alternative dependencies that are present. — Reply to this email directly, view it on GitHub <#762>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACRJEEBPNXEIDHDALNM2LDX4YA5ZANCNFSM6AAAAAA5LVSRLM> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[starksm64]

+1 on a requirement for exposing the component and platform/profile version. -1 on any additional JNDI binding as frankly those should be deprecated. I suggest we create an issue for adding this requirement to the specs for profiles and the platform and then hash the form(s) it needs to take. Certainly properties is one logical approach, but so could a version object that is populated with the records of version objects and be injectable: ``` public record VersionInfo(int major, int minor) { @OverRide public String toString() { return major+"."+minor; } } public interface WebProfile { VersionInfo ANNOTATION = new VersionInfo(3, 0); VersionInfo CDI = new VersionInfo(4, 1); ... VersionInfo SERVLET = new VersionInfo(6,1); } ```

…

On Thu, Sep 28, 2023 at 5:21 PM David Blevins ***@***.***> wrote: We're beginning to make more backwards incompatible changes to APIs and behavior, which is a totally fine evolution of the platform. I think this means we owe it to users to allow them to reliably and portably determine which exact specification version the application might be running in so they can act accordingly. A great deal of people write libraries that are used in multiple applications and those applications typically span a few Jakarta EE versions. There really needs to be an easy API an application can make use of to tell them what spec version they're running in. Before we get into proposals, what do you think about the goal? In terms of proposals, we could do JNDI calls, system properties, etc. The JVM takes the system property approach. We could possibly do the same using the short names of each spec. I.e. something like: - jakarta.platform.version = 10.0 - jakarta.core.version = 10.0 - jakarta.servlet.version = 6.0 - jakarta.pages.version = 3.1 - jakarta.batch.version = 2.1 ... etc FYI all the short names are used in both these places: - https://jakarta.ee/specifications/pages/ - https://github.com/jakartaee/pages/ The version would be just major+minor, no patch or service versions. The TCK of each spec would look for the system properties that relate to their spec. In whole, there would need to be a system property present for each spec the server implements. People would not only be able to use the system property to know what version is supported, but if there is support at all. For example, is MVC in the server? This is all information application developers can use to determine in code what kind of behavior they have. — Reply to this email directly, view it on GitHub <#762>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACRDMU677GAMAZEPY4ETVTX4YA5XANCNFSM6AAAAAA5LVSRLM> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[keilw]

I would also say JNDI is outdated, maybe more along the lines of a REST call along the lines of health or monitoring actuators in many popular runtimes. Werner

…

On 30.09.2023 18:09, Scott M Stark wrote: +1 on a requirement for exposing the component and platform/profile version. -1 on any additional JNDI binding as frankly those should be deprecated. I suggest we create an issue for adding this requirement to the specs for profiles and the platform and then hash the form(s) it needs to take. Certainly properties is one logical approach, but so could a version object that is populated with the records of version objects and be injectable: public record VersionInfo(int major, int minor) { @OverRide public String toString() { return major+"."+minor; } } public interface WebProfile { VersionInfo ANNOTATIONS = new VersionInfo(4, 0); VersionInfo CDI = new VersionInfo(4, 1); ... VersionInfo SERVLET = new VersionInfo(6, 0); } On Thu, Sep 28, 2023 at 5:21 PM David Blevins ***@***.***> wrote: > We're beginning to make more backwards incompatible changes to APIs and > behavior, which is a totally fine evolution of the platform. > > I think this means we owe it to users to allow them to reliably and > portably determine which exact specification version the application might > be running in so they can act accordingly. A great deal of people write > libraries that are used in multiple applications and those applications > typically span a few Jakarta EE versions. There really needs to be an easy > API an application can make use of to tell them what spec version they're > running in. > > Before we get into proposals, what do you think about the goal? > > In terms of proposals, we could do JNDI calls, system properties, etc. The > JVM takes the system property approach. We could possibly do the same using > the short names of each spec. I.e. something like: > > - jakarta.platform.version = 10.0 > - jakarta.core.version = 10.0 > - jakarta.servlet.version = 6.0 > - jakarta.pages.version = 3.1 > - jakarta.batch.version = 2.1 > ... > etc > > FYI all the short names are used in both these places: > > - https://jakarta.ee/specifications/pages/ > - https://github.com/jakartaee/pages/ > > The version would be just major+minor, no patch or service versions. The > TCK of each spec would look for the system properties that relate to their > spec. In whole, there would need to be a system property present for each > spec the server implements. People would not only be able to use the system > property to know what version is supported, but if there is support at all. > For example, is MVC in the server? This is all information application > developers can use to determine in code what kind of behavior they have. > > — > Reply to this email directly, view it on GitHub > <#762>, or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AACRDMU677GAMAZEPY4ETVTX4YA5XANCNFSM6AAAAAA5LVSRLM> > . > You are receiving this because you are subscribed to this thread.Message > ID: ***@***.***> > — Reply to this email directly, view it on GitHub <#762 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAARGYDNO7AT4QNF7RIZXELX5A7Z3ANCNFSM6AAAAAA5LVSRLM>. You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[keilw]

Maybe something similar to the Spring Boot /info actuator: https://howtodoinjava.com/spring-boot/info-endpoint-custom-info/

[edburns]

Consider this comment.

It is better to use interface methods with default implementations. For example.

public interface WebProfile {

   static WebProfile instance() {
    ...
    }

   default VersionInfo annotations() {
      new VersionInfo(3, 0);
   }
}