Module names for Jakarta EE specifications

[ivargrimstad]

The PMC recommends using jakarta.* as module names for the Jakarta EE specification projects.

Please add comments and/or suggestions to this issue.

[kwsutter]

Since the Specification Process has just been released for its first public draft review, maybe we need to clarify what a Specification Project is...

Link to the Draft Spec Process: https://docs.google.com/document/d/1ongNUyGvZPtrcuxA7RQNV2qBESFcAphQbzdk3pUIQ5s/edit#

Specification Project: An Eclipse Foundation Project operating under the EDP and EFSP that is constituted to deliver Specification Versions.
Specification Version: A specific version of a Specification.
Specification: A collection of Application Programming Interface (API) definitions, descriptions of semantic behavior, data formats, protocols, and/or other referenced specifications, along with its TCK, intended to enable the development and testing of independent Compatible Implementations.

Thus, for this issue, we are talking specifically about module names for the Jakarta EE APIs.

HTH, Kevin

[mkarg]

There is one problem with the module name: JAX-RS (and possibly other specifications) already has published under a different module name already since Java EE 8. So if we change to the new module name, applications have to be recompiled. This is a no-go for just a minor version. So we only can switch to the new module name in our next major version, which is planned for 2019. For Jakarta EE 8 this means, it MUST contain JAX-RS still with old module name, OR we will force some existing applications to fail unless recompiled.

[m-reza-rahman]

Isn't this a bit of a no-brainer or am I missing something? What would be the alternative? ee.jakarta.? org.eclipse.jakarta.ee?

[rhuan080]

org.eclipse.jakarta is good for me.

[aguibert]

Here are some useful articles on the topic of module naming conventions:

• Java SE 9 - JPMS module naming
• How to name modules, automatic and otherwise

Best practice recommends reverse-DNS naming, just like package names. This means we should be starting with org.*. For this reason I think org.jakarta.* or org.eclipse.jarkata.* would be acceptable prefixes. The shorter the better, but it should match whatever package name prefix we choose for any new JEE APIs.

Regarding JAX-RS, it seems they have jumped the gun with module naming. It would be nice if all JEE specs followed a common pattern, but they have chosen java.ws.rs, which does not follow reverse-DNS naming conventions and starts with java.* which should be reserved for Java SE platform modules. A potential migration path we could take here is creating a new module for JAX-RS that follows proper naming conventions and then change the original JAX-RS 2.1 module to require it, so something like:

@Deprecated
module java.ws.rs {
  requires transitive org.jakarta.ws.rs; // or whatever the official name for JAX-RS module is
}

[julianjupiter]

I'm okay with jakarta.* .For me, that's the best option. It is equally good as javax.* .I don't know but that is more appealling than org.eclipse.jakarta.*.

[kwsutter]

The shorter the better, but it should match whatever package name prefix we choose for any new JEE APIs.

Right. The proposed package name prefix for new Jakarta EE specifications will be jakarta., so it should follow that the JPMS module names should also start with jakarta..

This also follows the Maven Group and Artifact ID convention of prefixing with jakarta.*. Consistency is good.

As far as JAX-RS... Since there was no defined module naming convention for Java EE 8, it looks like JAX-RS jumped the gun. So, whatever is decided via this discussion will need to be applied across the board with all Jakarta EE components. JAX-RS may need to follow the deprecation route described earlier...

BTW, we can not use java.* nor javax.* as the module name prefix.

[mkarg]

@kwsutter Nobody jumped the gun. It was an active decision of the JCP's JSR 370 expert group to include a module name in JAX-RS 2.1 contained in Java EE 8, and it was Oracle that decided about that name, and Oracle had all rights to use it. For backwards compatibility we MUST NOT change it in 2.x, and we have all rights to keep it unless Oracle explicitly forbids it, which they have not so far. So there is no actual technical or legal need to change it. I propose to change it in 3.x contained in Jakarta EE 9 to be least disruptive. Anyways, such a change has to be agreed upon by the committers, so the PMC should file a PR ASAP.

[m0mus]

FYI, I am reposting here email from @bshannon with the original proposal:

There's several approaches I can see for defining module names for
Jakarta EE specifications:

1. Use jakarta.* for all Jakarta EE module names.  This is consistent
  with the use of Maven groupIds.  To avoid breaking compatibility for
  any applications using the existing module names defined by Java SE
  we would need to create aggregator modules to allow these modules to
  be available with both the java.* and jakarta.* module names, e.g.,
  "module java.transaction { requires transitive jakarta.transaction; }"

2. Use jakarta.* for all Jakarta EE module names except for those
  modules already defined by Java SE.  This preserves compatibility
  with the Java SE modules without the need for aggregator modules,
  but results in an inconsistent module namespace.

3. Use java.* for all Jakarta EE module names for existing Java EE
  specifications (those licensed to use the javax.* package namespace).
  This will result in some future specifications using different module
  names (as well as package names).  This would require us to decide
  on the java.* module names to include in the Java trademark license.

The first option has PMC preference.

[NottyCode]

I like jakarta.* since it matches what is established for maven coordinates and package names.

On the JAX-RS question I think it could be argued that changing the module name in a . release is ok. There is a way to map the old to new names and updating a module-info wouldn’t be a significant undertaking. To me it is a bit like changing your maven dependencies, which I expect people will be doing if they are upgrading.

[rotty3000]

Let's assume that the prefix does indeed become jakarta.*.

I'd like to discuss the suffix.

There have been several different patterns for suffix over the years. And there's some level of consistency between the artifact names (particularly; maven artifactId), Bundle-SymbolicName and more recently Automatic-Module-Name.

Just consider the aforementioned JAX-RS.

• Artifact Name: javax.ws.rs-api
• Bundle-SymbolicName: javax.ws.rs-api
• Automatic-Module-Name: java.ws.rs

The most recent and prolific pattern seems to be ${API_PACKAGE}-api but as you can see JAX-RS went ahead with a module name without the -api suffix.

One point to consider is the implication that the module name identifies the contract of the module's API in so much that any artifact that intends to be an alternative provider of said contract MUST use the same module name (because consumers will require by module-name). As such there may be a valid reason to distinguish between packaging/artifact names and the module name.

[tjwatson]

Ray, I agree that the artifact name need not match the module name. But I think we must consider having the Bundle-SymbolicName match the module name as much as possible since require-bundle semantics closely match the semantics of Java module requires.

[jodastephen]

As the author of this document on module naming referenced above, let me make a quick comment. The use of jakarta.* as module names would not normally be recommended as you don't own the jakarta TLD. (Oracle does own the .'java TLD).

However, given the importance of Jakarta EE to the Java landscape, I think it is reasonable to have a special case. In particular, org.eclipse.jakarta seems over the top for these key spec modules. Thus I favour jakarta.* for the spec module names.

I note that this issue hasn't discussed package names. I'd prefer to see the package names for specifications to also be jakarta.*. Thus, the module name and package name would match as per my document.

[bshannon]

@rotty3000
I addressed some of these issues in my message about implementation module names.
It's probably best to continue that conversation there. And I agree that the module name
corresponds to the API, not the implementation.

@jodastephen
We're not going to rename the existing packages from javax.* to jakarta.* because it would break compatibility with all the existing Java EE applications. Very few existing applications depend on the module name.

[bshannon]

PMC, what's the plan for closing this issue? How long do you want to leave it open for additional comments? Or is there some specific event that needs to occur before this can be closed?

[ivargrimstad]

We will close it on Tuesday at our pmc meeting...

On Wed, 31 Oct 2018, 19:53 Bill Shannon, ***@***.***> wrote: PMC, what's the plan for closing this issue? How long do you want to leave it open for additional comments? Or is there some specific event that needs to occur before this can be closed? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#34 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAJGxNtIA0Q6PtKMUFFKUN8Z0JLDAt92ks5uqfGqgaJpZM4XkHh8> .

-- Java Champion, JCP EC/EG Member, EE4J PMC, Jakarta EE WG Member, JUG Leader

[ivargrimstad]

According to discussions in the PMC following this thread, the PMC will issue a statement saying that jakarta.* will be a requirement as module names for future releases. The current release should keep the module names as defined in the Java EE 8 version of the spec, or no module name at all.

[arjantijms]

Practically this seems to have changed though, as Tycho and p2 demand Jakarta.*.

[mkarg]

Maybe a misconfigured or buggy plugin?

[xeno6696]

BTW, we can not use java.* nor javax.* as the module name prefix.

I'm one of OWASP's esapi-java-legacy co-leads.

Could you expand on this a bit more?

Our library has extreme requirements for backwards compatibility. (We just updated in the last year to minimally support JDK 1.8)

We are currently trying to assess how best to move forward here: just yesterday we had a slew of developer complaints come in, it's important to note that our library averages 350k downloads/month. The current ESAPI version is incompatible with the namespace issue and this puts us into a terrible bind. Switching our library to use jakarta will break it for tens of thousands of applications that aren't ready to run with a new servlet-api. Frameworks like Spring mandate jakarta (now) and to be truthful, changing a package name like this shouldn't be taken lightly. We have to be able to support javax and jakarta, but this hard change... usually you deprecate something and allow several years of warnings to build. We've been coding to the servlet standard and if that is suddenly switching then there should be some sort of a grace period to allow library maintainers like us to do something that isn't a kludgey hack (like creating a separate release just for jakarta.)

WHY can we no longer use the javax.* package name?