Run brXM 15 on Java 17

Overview

This guide describes how to build and run a brXM 15 project on Java 17.

When to Use

Bloomreach officially supports Java 11 for brXM 15. brXM 15 is tested and verified only with Java 11. Running brXM 15 on Java 17 is not supported or tested by Bloomreach. Use this guide if you need to run brXM 15 on Java 17 and accept the associated risks.

This guide assumes you have a brXM 15 project created from the Maven archetype.

Prerequisites

• brXM 15 project created from the Maven archetype
• Java 17 installed
• Familiarity with Maven and project configuration

Implementation Steps

1. Configure JVM Access with --add-opens

Some libraries in brXM 15 require access to non-public fields and methods in Java core APIs. Java 17 restricts this access by default. You must use the --add-opens option to enable it.

Local Cargo Development Environment

Override the cargo.jvmargs property in the cargo.run profile of your root pom.xml:

  <artifactId>cargo-maven2-plugin</artifactId>
  <configuration>
    <configuration>
      <properties>
        <cargo.jvmargs>
          <![CDATA[-agentlib:jdwp=transport=dt_socket,address=${cargo.debug.address},server=y,suspend=${cargo.debug.suspend} -noverify ${javaagent} --add-opens java.base/java.util=ALL-UNNAMED ${cargo.jvm.args}]]>
        </cargo.jvmargs>
      </properties>
copy

Deployed Environments

Add the --add-opens option to the JVM_OPTS environment variable. For details, see Configure the Application Server (Apache Tomcat on Linux).

2. Update Byte Buddy Dependency

The dynamic content beans feature in brXM 15 uses Byte Buddy. The version included with brXM 15 is incompatible with Java 17. Update the Byte Buddy dependency as follows.

a. Set Byte Buddy Version in Root pom.xml

Add the following property to the <properties> section:

<bytebuddy.version>1.12.21</bytebuddy.version>

b. Exclude Byte Buddy from hippo-package-site-dependencies

In site/components/pom.xml, locate the hippo-package-site-dependencies dependency and add an exclusion for byte-buddy:

    <dependency>
      <groupId>org.onehippo.cms7</groupId>
      <artifactId>hippo-package-site-dependencies</artifactId>
      <type>pom</type>
      <exclusions>
        <exclusion>
          <groupId>net.bytebuddy</groupId>
          <artifactId>byte-buddy</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
copy

c. Add Byte Buddy as a Direct Dependency

Add the following dependency:

    <dependency>
      <groupId>net.bytebuddy</groupId>
      <artifactId>byte-buddy</artifactId>
      <version>${bytebuddy.version}</version>
    </dependency>
copy

Note: To disable dynamic content beans instead, use the -Ddynamic.bean.generation=false flag.

3. Rebuild and Run the Project

After applying these changes, build and run your brXM 15 project with Java 17.

Verification

• The project should build successfully without errors.
• The application should start and function as expected on Java 17.

Troubleshooting

• If you encounter errors related to module access, verify that the --add-opens option is correctly configured.
• If you see Byte Buddy compatibility errors, confirm that the correct version is specified and that exclusions are set as described.

Important

Bloomreach does not support or guarantee brXM 15 operation on Java 17. Use this configuration at your own risk.