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.