PAYARA-3924: Payara BOM

[pdudits]

Description

This is a feature.

Bill of material module lists all the APIs, third-party libraries and Arquillian containers fit for particular release. The goal is to enable downstream users (and e. g. our test projects) to always have proper dependencies for microprofile APIs, third-party libraries like Jackson and Jersey and up-to-date container implementations driven by single input - the version of target Payara server.

General structure is following:

• Top-level module (payara-aggregator) defines the versions as properties
• payara-bom inherits those via api-parent ⇾ payara-aggregator
• BOM defines the dependencies in dependencyManagement section
• It is imported in payara-nucleus-parent to make these entries available for the rest of the build

An artifact is put in BOM when:

• It is Jakarta EE, Microprofile, OSGi or Java EE API that is compatible with the release
• It is public artifact of the release (distribution, arquillian container)
• It is major implementation component with many optional artifacts users may use (HK2, Jersey, Jackson, Hazelcast), or is frequently used separately in application e.g. for tests.
• When BOM is available for such third-party component, entire BOM is imported

A BOM is to be used:

• By the build itself
• By users to refer to APIs, and e.g. Jackon and Jersey components that are not part of server
  • In import scope
  • It can be useful to support BOM as a parent to
    • Bring patched-externals repository into the project
    • Allow user to use version properties to import related artifacts
    • Control the versions by redefining properties (if they're feeling lucky)

Scopes are defined as provided for major aggregation apis - javaee-api, jakarta.jakartaee-api, microprofile. Arquillian containers are defined as test. Anything else is left at compile to keep user surprises at minimum (and to prevent the need at redefining scopes within main codebase).

The POM file is flattened to contain all relevant information from parent poms and be standalone -- check version in target/flattened-pom.xml or the one that gets installed into your local repo.

Testing

Testing Performed

[x] Clean build with empty repository
[x] compare dependency trees of the project before and after the change (see
deptree-diff.patch.gz)
[x] make test application that imports a BOM and utilizes Arquillian (all containers) payara/Payara-Examples#115
[ ] make test application that uses BOM as parent to utilize properties (i. e. TCK runner)

Test suites executed

Testing Environment

Zulu JDK 1.8_222 on Windows 10 with Maven 3.6.2 and constantly cleaned fish.payara.server.internal group in local Maven repo.

Documentation

[ ] T. B. D.

[pdudits]

I'll build up examples inhttps://github.com/payara/payara-examples, already the first steps look promising:

With minimal pom like:

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <artifactId>bom-import</artifactId>
    <packaging>war</packaging>
    <dependencyManagement>
        <dependencies>
            <!-- All server dependencies at your hand -->
            <dependency>
                <groupId>fish.payara.api</groupId>
                <artifactId>payara-bom</artifactId>
                <version>5.194-SNAPSHOT</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <!-- Some of the referenced projects in POM are Payara's patched versions. These are published in following repo: -->
    <repositories>
        <repository>
            <id>payara-patched-externals</id>
            <name>Payara Patched Externals</name>
            <url>https://raw.github.com/payara/Payara_PatchedProjects/master</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>jakarta.platform</groupId>
            <artifactId>jakarta.jakartaee-api</artifactId>
        </dependency>
        <dependency>
            <groupId>org.eclipse.microprofile</groupId>
            <artifactId>microprofile</artifactId>
            <type>pom</type>
        </dependency>
    </dependencies>
</project>

We can already see the the value:

 --- maven-dependency-plugin:2.8:tree (default-cli) @ bom-import ---
[INFO] fish.payara.examples:bom-import:war:1.0-SNAPSHOT
[INFO] +- jakarta.platform:jakarta.jakartaee-api:jar:8.0.0:provided
[INFO] \- org.eclipse.microprofile:microprofile:pom:3.0:provided
[INFO]    +- javax.enterprise:cdi-api:jar:2.0:provided
[INFO]    |  +- javax.el:javax.el-api:jar:3.0.0:provided
[INFO]    |  +- javax.interceptor:javax.interceptor-api:jar:1.2:provided
[INFO]    |  \- javax.inject:javax.inject:jar:1:provided
[INFO]    +- javax.ws.rs:javax.ws.rs-api:jar:2.1:provided
[INFO]    +- javax.json.bind:javax.json.bind-api:jar:1.0:provided
[INFO]    +- javax.json:javax.json-api:jar:1.1:provided
[INFO]    +- javax.annotation:javax.annotation-api:jar:1.3:provided
[INFO]    +- org.eclipse.microprofile.config:microprofile-config-api:jar:1.3:provided
[INFO]    |  \- org.osgi:org.osgi.annotation.versioning:jar:1.0.0:provided
[INFO]    +- org.eclipse.microprofile.fault-tolerance:microprofile-fault-tolerance-api:jar:2.0.1:provided
[INFO]    +- org.eclipse.microprofile.health:microprofile-health-api:jar:2.1:provided
[INFO]    +- org.eclipse.microprofile.metrics:microprofile-metrics-api:jar:2.0.1.payara-p1:provided
[INFO]    +- org.eclipse.microprofile.jwt:microprofile-jwt-auth-api:jar:1.1.payara-p1:provided[INFO]    +- org.eclipse.microprofile.openapi:microprofile-openapi-api:jar:1.1.2:provided     [INFO]    +- org.eclipse.microprofile.rest.client:microprofile-rest-client-api:jar:1.3.4:provided
[INFO]    \- org.eclipse.microprofile.opentracing:microprofile-opentracing-api:jar:1.3.1:provided

Note, that the versions of imported microprofile API do not match those of microprofile 3.0, but those of Payara Server (rest-client 1.3.4, jwt-auth 1.1.payara-p1. javax apis imported via microprofile aggregate are not ideal, but are ok in provided scope -- we do offer similar support for main javax apis as well.

[pdudits]

Adding arquillian container we see jersey version is overriden to match server (Hooray!):

\- fish.payara.arquillian:arquillian-payara-server-managed:jar:1.2:test
[INFO]    +- fish.payara.arquillian:payara-container-common:jar:1.2:test
[INFO]    |  +- org.glassfish.jersey.core:jersey-client:jar:2.29.1.payara-p1:test
[INFO]    |  |  +- jakarta.ws.rs:jakarta.ws.rs-api:jar:2.1.5:test
[INFO]    |  |  \- org.glassfish.hk2.external:jakarta.inject:jar:2.6.1.payara-p1:test
[INFO]    |  +- org.glassfish.jersey.inject:jersey-hk2:jar:2.29.1.payara-p1:test
...

[pdudits]

Jenkins test please

[pdudits]

Jenkins test please

[pdudits]

Jenkins test please

[Pandrex247]

Seems to now work against my test (MicroProfileOnMicro - see Payara Examples PRs)
I've also checked that the javadoc and source still generate correctly after the pom shuffles