What to do about Liberty API/SPI built on Java EE interfaces/classes

[njr-11]

It needs to be determined what the expectations are for the JavaEE/Jakarta transformation tool around IBM API that includes Java EE classes.

For example, a security feature has this API package,

IBM-API-Package: com.ibm.wsspi.security.auth.callback; type=“ibm-api”, \

A couple of the classes in this package declare interface methods that use JCA spec types as parameters and results types. For example:

/com.ibm.ws.security.jaas.common/src/com/ibm/wsspi/security/auth/callback/WSManagedConnectionFactoryCallback.java

and here is some of the content of the class,

import javax.resource.spi.ManagedConnectionFactory;
import javax.security.auth.callback.Callback;
...
    public void setManagedConnectionFactory(ManagedConnectionFactory managedConnectionFactory) {
    …
    public ManagedConnectionFactory getManagedConnectionFacotry() {
    …

Here’s the public JavaDoc for the above,
https://www.ibm.com/support/knowledgecenter/SS7K4U_liberty/com.ibm.websphere.javadoc.liberty.doc/com.ibm.websphere.appserver.api.security_1.2-javadoc/com/ibm/wsspi/security/auth/callback/WSManagedConnectionFactoryCallback.html

The transformation tool would naturally create two versions of the same API/SPI interface, one in terms of Jakarta EE packages and the other in terms of Java EE packages. That means there would be two different, conflicting JavaDocs for these two versions of the external API/SPI. Can processes for externalizing JavaDoc cope with that? Will it confuse users? And is it the approach we want to take?

Or, do we need to define new packages or interface names and build in that awareness for all such cases to the transformation tool such that it can convert usage of these API/SPI within customer apps as well as what is strictly Java EE spec usage? If so, where will we put it /what will we call it so that it does not confuse users? If we did put it in a different package, would we move all of the other classes within that API package as well even if some of them don't have dependencies on Java EE?

What could this look like using the example above?

Option 1: same class and package name, different maven coordinates

com.ibm.wsspi.security.auth.callback.Constants 	 
com.ibm.wsspi.security.auth.callback.WSAppContextCallback 	
com.ibm.wsspi.security.auth.callback.WSCallbackHandlerFactory 	
com.ibm.wsspi.security.auth.callback.WSManagedConnectionFactoryCallback
com.ibm.wsspi.security.auth.callback.WSMappingCallbackHandler 
com.ibm.wsspi.security.auth.callback.WSMappingPropertiesCallback 
com.ibm.wsspi.security.auth.callback.WSServletRequestCallback 	
com.ibm.wsspi.security.auth.callback.WSServletResponseCallback 	
com.ibm.wsspi.security.auth.callback.WSX509CertificateChainCallback

Option 2: Same package, but add a Jakarta prefix

com.ibm.wsspi.security.auth.callback.Constants // has no Java EE dependency
com.ibm.wsspi.security.auth.callback.JakartaAppContextCallback 	
com.ibm.wsspi.security.auth.callback.JakartaCallbackHandlerFactory 	
com.ibm.wsspi.security.auth.callback.JakartaManagedConnectionFactoryCallback
com.ibm.wsspi.security.auth.callback.JakartaMappingCallbackHandler 
com.ibm.wsspi.security.auth.callback.JakartaMappingPropertiesCallback 
com.ibm.wsspi.security.auth.callback.JakartaServletRequestCallback 	
com.ibm.wsspi.security.auth.callback.JakartaServletResponseCallback 	
com.ibm.wsspi.security.auth.callback.JakartaX509CertificateChainCallback

• many API/SPI don't use the WS prefix, so the above won't always be so natural

Option 3: Use a different package name, but same class names

com.ibm.wsspi.security.auth.callback.jakarta.Constants  
com.ibm.wsspi.security.auth.callback.jakarta.WSAppContextCallback 	
com.ibm.wsspi.security.auth.callback.jakarta.WSCallbackHandlerFactory 	
com.ibm.wsspi.security.auth.callback.jakarta.WSManagedConnectionFactoryCallback
com.ibm.wsspi.security.auth.callback.jakarta.WSMappingCallbackHandler 
com.ibm.wsspi.security.auth.callback.jakarta.WSMappingPropertiesCallback 
com.ibm.wsspi.security.auth.callback.jakarta.WSServletRequestCallback 	
com.ibm.wsspi.security.auth.callback.jakarta.WSServletResponseCallback 	
com.ibm.wsspi.security.auth.callback.jakarta.WSX509CertificateChainCallback

• should Constants class get copied due to being in the same package? It has no Java EE dependencies of its own

[NottyCode]

Current view is to go with option 1 because it is a simpler to just update the maven dependency.

[isaacrivriv]

We also need to determine what versioning to use if transformed packages with the same name as the original packages are included since they have moved to the Jakarta namespace. The idea would be to let the transformer determine which version the transformed packages should be as stated by the issue eclipse/transformer#20. Discussions on Slack about the issue can be found here and here

[jhanders34]

At the design issues call yesterday, we decided to update the package that include Jakarta API in their arguments or return types to be version 10.0 when transforming to Jakarta EE 9 APIs. This will allow for the WebSphere IDE plugins to find the right version of the APIs to compile against.

[jhanders34]

To resolve this issue, the transformer issue eclipse/transformer#174 needs to be resolved.