Skip to content

Open Liberty JakartaEE Enablement

Jump to bottom
chackoj edited this page Jul 9, 2020 · 6 revisions

General info

General steps for feature enablement

  • Identify if feature has a implementation bundle or uses 3rd party implementation (Weld, Apache CXF etc...)
    • Implementation bundle jars will enable transformation by adding the new BND directive (jakartaeeMe: true).
    • 3rd Party would download Jakarta 9 implementation jars.
  • Create Jakarta versions of Open-liberty features.
  • Create API feature projects for Jakarta API JARs.
  • Create projects for io.openliberty API jars - depending on jakarta ee signatures.
  • Enable JakartaEE9 repeat of FAT tests.
  • Add completed feature to convenience features (jakartaee-9.0, jakartaeeClient-9.0, webProfile-9.0)
  • Notify CTS when the enablement is complete.

Enabling transformation of bundle jars

You will need to identify the bundle jars which are related to your function.

Identifying jars

When updating a particular feature to jakarta, it will be helpful to first review the com.ibm.websphere.appserver.features feature file. The particular feature file will give a list of features, bundles, and jars that are used for your particular feature. Additionally, you can run the python script (search below for "javax-manifest-search") to cross check which bundles should be transformed.

Minify Steps

  1. Creating a Liberty Image which only contains the necessary jars.
  2. Acquire desired Liberty Image, and enable the selected feature[s].
  3. To Minify, run the following command from the wlp/bin directory: "./server package --include=minify"
  4. Unzip the created minified image.
  5. The manifest of the wlp/lib jars will need to be inspected for javax references.
    1. Requires searching all "Import-Package" values of the MANIFEST.MF files.
  6. Use this python script: https://github.ibm.com/Volodymyr-Siedlecki/javax-manifest-search
    1. First extract the manifests using "unzip", and then run the script to find matches.
  7. Once they have been identified, continue with the next step to enable Jakarta transformation during liberty build process.
  8. This output contains the bundles that need the 'jakartaeeMe: true' attribute added their bnd.bnd.
    1. Note that the list of bundles from the script's output may differ from the bundles activated from the .feature files. Since some features activate others, they may be overlap with bundles in the minfied image.
  9. In some cases, you may also want to run this script on the wlp/dev/api/spec jars, in case some of the bundles use a API that relies on javax. That jar can also be transformed if there is no jakarta equivalent.
  10. These core/kernel bundles don't need to be transformed. Kernel bundles

Transformation

  • Only bundle jars which have dependencies on javaEE APIs which are included in jakarta need to be transformed.

  • To transform a bundle jar, add this directive to the bundle project BND file: jakartaeeMe: true

  • The directive causes a transformed jakarta bundle jar to be created in addition to the usual bundle jar which is already created: <bundle-name>.jakarta.jar

  • To test invocation of the transformation tool, change to the open-liberty "dev" folder and run: ./gradlew <bundle-proj-name>:assemble

  • Universal transformation rules are specified in the project: wlp-jakartaee-transform

  • Almost certainly, when enabling new function areas, additions will need to be made to the transformation rules. An explanation of the rules, where they are located, and changes needed is here: Transformation Rules

Creation of jakarta open-liberty features

  • Open-liberty features for jakarta are added by hand.
  • At this time all features should use "kind: noship".
  • The new jakarta features are generally created by copying the project of an existing javax open liberty feature, updating the feature name appropriately, and updating the feature metadata to point to the jakarta bundle jars.
    • For example, we created a servlet-5.0 feature by copying the servlet-4.0 then editing the copy to point to the new *.jakarta bundles.
  • Inspect the feature metadata: If the feature depends on “com.ibm.websphere.appserver.javaeeCompatible-8.0”, change the dependency to “com.ibm.websphere.appserver.eeCompatible-9.0".

Creation of projects for jakarta API jars:

A first step is to ensure that the jakarta API jar is available on the open-liberty artifactory repository.

Creation of projects for com.ibm API jars.

FAT test enablement:

FAT test are enabled to run using JakartaEE9 features using a new FAT test repeat case.

Add to convenience features

Add your completed feature to the list of features enabled by the convenience features

  • jakartaee-9.0
  • jakartaeeClient-9.0
  • webProfile-9.0

These features are used by CTS, so its important you test enablement using these special features

Notification of CTS:

When a build is available for the newly enabled function, contact Asosa Khoddamhazrati, and Brian Decker in the CTS team, to let them know that CTS can be started on the function.

Sample Changes

Sample changes made for servlet-5 are located on the pull request: https://github.com/OpenLiberty/open-liberty/pull/11177

The pull request contains several categories of updates. These include:

  1. Updates to the build steps to pull in the transformation tool, and to update build steps to invoke the tool according to the setting of the new "jakartaeeMe" BND directive.
  2. Addition of the jakarta servlet API jar.
  3. Addition of the servlet-5 feature.
  4. Addition of "jakartaeeMe: true" to servlet-5 related bundles.
  5. Additional custom resource steps which are specific to servlet-5.
Clone this wiki locally