This proposal has been approved and the Eclipse Transformer project has been created.
Visit the project page for the latest information and development.

Eclipse Transformer

Thursday, March 5, 2020 - 14:26 by BJ Hargrave
This proposal is in the Project Proposal Phase (as defined in the Eclipse Development Process) and is written to declare its intent and scope. We solicit additional participation and input from the community. Please login and add your feedback in the comments section.
Parent Project
Proposal State
Created
Background

Jakarta EE 8 is binary compatible with its ancestor Java EE 8 using java packages which start with the javax. package prefix. After Jakarta EE 8, all API changes to any Jarkata EE specification will require a renaming effort to move away from the javax. package prefix.

The specifics of this renaming and the new names are still a subject of discussion within the Jakarta EE community, but, for a significant portion of the packages, renaming will be necessary for Jakarta EE releases after release 8.

Tools are always important to take the drudgery away from developers, so this project was created in response to the community need to work with existing Java artifacts using the old javax. package names in the new Jakarta EE world using the renamed packages.

Scope

Eclipse Transformer provides tools and runtime components that transform Java binaries, such as individual class files and complete JARs and WARs, mapping changes to Java packages, type names, and related resource names.

While the initial impetus for the project was the Jakarta EE package renaming issue, the scope of the project is broader to support other renaming scenarios. For example, shading.

Description

The project can mutate individual class files and thus could be used in a class loader to dynamically rename type references at runtime while classes are being loaded. This could allow a program such as an application server to use this support in its class loaders to allow existing libraries using older type name, such as javax. types, to be transformed, loaded and executed in a newer environment using renamed types.

The project can also mutate all types in a JAR or WAR file. This could be used during a tooling phase to process dependencies and application jars prior to assembly so that all the classes are transformed to the renamed types.

The tools are rule driven which allow users to control which class files in a JAR/WAR are transformed and how they are transformed. Different users may want different rules depending upon their specific needs. So the tools can be used for any renaming challenge, not just the specific Jakarta EE package renames.

The tools provides an API allowing it to be embedded in a runtime to dynamically transform class files during the class loader definition process. The API also supports transforming JAR files. A CLI is also provided to allow use from the command line. Ultimately, the tools can be packaged as Gradle and Maven plugins to incorporate in a broader tool chain.

The tools are based upon the class file and JAR file manipulation capabilities of the the Bnd tool. Bnd will be a dependency of the tools and is not part of the project.

Why Here?

The Eclipse Foundation is the home the Jakarta EE community and the community must deal with the package renaming issue. Having an open tools project which can be used in common by the community can help in dealing with the challenges of the renaming issue.

Project Scheduling

The intial contribution is already available in https://github.com/tbitonti/jakartaee-prototype

The Eclipse project can be provisioned as soon as ready.

Future Work

There is a list of possible future work at https://github.com/bjhargrave/transformer/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement.

This list includes:

  • Define rules for String constant mutation
  • Handle Nest attributes
  • Handle JPMS module metadata
  • Intercept Class.forName and similar calls to perform package renaming dynamically
  • Handle OSGi metadata
Initial Contribution

The initial contribution is at https://github.com/tbitonti/jakartaee-prototype

This project is under AL2 license.

Source Repository Type