Skip to content

JakartaEE Transformation Rules

Jump to bottom
Chuck Bridgham edited this page Apr 20, 2020 · 2 revisions

Transformation steps are performed by default on all resources of the bundle jar.

Properties files are used to control the particular resources which are selected to be transformed, and to specify the particular updates which are to be made to each resource.

Five types of updates are currently supported. These include:

  1. Package renames
  2. Package version updates
  3. Bundle identity updates
  4. Java class string updates
  5. XML updates

Package Renames

Package rename type updates are updates to class references to javaEE classes, where a reference to a javaEE class is changes to reference a jakarta class.

For example:

javax.inject=jakarta.inject
javax.servlet=jakarta.servlet
javax.servlet.annotation=jakarta.servlet.annotation
javax.servlet.descriptor=jakarta.servlet.descriptor
javax.servlet.http=jakarta.servlet.http
javax.servlet.resources=jakarta.servlet.resources
  • Package renaming is performed on all class references which occur in class type resources, and which occur in manifest files.
  • Generally, what package renaming rules must be added for each new jakarta API which is being enabled. The above cases are needed for the servlet API.

Package Version Updates

Package version type updates are updates to the package version which appears in a bundle manifest. This is a necessary update in addition to the replacement of javaEE package names, and occurs at the same time and in conjunction with the package name update.

For example:

jakarta.servlet=[5.0,6)
jakarta.servlet.annotation=[5.0,6)
jakarta.servlet.descriptor=[5.0,6)
jakarta.servlet.http=[5.0,6)
jakarta.servlet.resources=[5.0,6)
  • The particular versions are according to the versions of the jakartaEE packages. Generally, these are updated to include a version number one higher. As a reminder, [ ] is inclusive, and ( ) is exclusive.

Bundle Identity Updates

These are updates to bundle manifest files which are made to internally rename the bundle.

For many bundles, the default rule should be used. That is:

*=*.jakarta,2.0,+" Jakarta",+"; Jarkata Enabled"
  • The meaning of this default rule is to apply the manifest of all bundles which are invoked by the transformation tool, to update the bundle symbolic ID as specified by the bundle manifest to append ".jakarta', to set the bundle version to "2.0", to append " Jakarta" (including the space) to the bundle name, and to append "; Jakarta Enabled" (including the "; " characters) to the bundle description.

For example:

Bundle symbolic name: com.ibm.ws.webcontainer.servlet.4.0 --> com.ibm.ws.webcontainer.servlet.4.0.jakarta
Bundle name: WAS WebContainer --> WAS WebContainer Jakarta
Bundle description: WAS WebContainer 8.1 with Servlet 4.0 support --> WAS WebContainer 8.1 with Servlet 4.0 support; Jarkata Enabled

Java Class String Updates

  • These are updates to java string constants.
  • Updates are whole string replacements. (This may be changed, depending on the need for more flexible update strategies.)
  • Whole string updates are performed in addition to string updates which are driven by package renames.

XML String Updates:

These are simple find/replace updates made to the text of XML files.

  • The XML files are treated as simple UTF-8 encoded text files, and are updated using a simple string substitution rule which replaces initial string values with final string values whereever the initial values appear in the XML text.
  • XML updates use a more sophisticated pattern for determine what substitutions are to be performed on particular XML files. The pattern is to use a two-step set of rules files. A top master rules file maps simple expressions to bottom rules files. The bottom rules files map initial values to final values.

For example, the XML rules might be specified as:

The top master rules file ...
 jakarta-xml-master.properties

... which points to three bottom specific rules files ...
server.xml=jakarta-xml-server.properties
web.xml=jakarta-xml-web.properties
*.xml=jakarta-xml-all.properties

... and for which "jakarta-xml-server.properties" contains initial-final value pairs which are to be used to
update "server.xml" files, "jakarta-xml-web.properties" is used to update "web.xml" files, and "jakartaxml-all.properties"
is used to update all XML files other than server.xml and web.xml files.

Globals Rules Files

The current global rules files are located at:

Rules for package renames:

dev/wlp-jakartaee-transform/rules/jakarta-renames.properties

Rules for package version updates:

dev/wlp-jakartaee-transform/rules/jakarta-versions.properties

Rules for bundle identify updates:

dev/wlp-jakartaee-transform/rules/jakarta-bundles.properties

Rules for resource selection:

dev/wlp-jakartaee-transform/rules/jakarta-selections.properties

Rules for direct string updates:

dev/wlp-jakartaee-transform/rules/jakarta-direct.properties

Rules for direct string updates:

dev/wlp-jakartaee-transform/rules/jakarta-direct.properties

Master rules for xml updates:

dev/wlp-jakartaee-transform/rules/jakarta-xml-master.properties

Additional rules for xml updates:

dev/wlp-jakartaee-transform/rules/jakarta-xml-<tag>.properties
Clone this wiki locally