How to Build TNT4J-Stream-JMX

This article explains how to build TNT4J-Stream-JMX using Maven. It outlines mandatory and optional modules, required dependencies, manual library setup when needed, and the steps to package and run the project.

• (M) marked modules are mandatory
• (O) marked modules are optional
• (U) marked modules are utility modules (e.g., performs compiled assemblies packaging)

Modules list:

• Core (M) - implements core JMX sampling, processing and dissemination features. Maven dependency:

     <dependency>
         <groupId>com.jkoolcloud.tnt4j.stream</groupId>
         <artifactId>tnt4j-stream-jmx-core</artifactId>
         <version>12.0.5</version>
     </dependency>

• J2EE (O) - J2EE API addition to handle J2EE API defined attributes and implements abstract Stream-JMX servlet API. Maven dependency:

     <dependency>
         <groupId>com.jkoolcloud.tnt4j.stream</groupId>
         <artifactId>tnt4j-stream-jmx-j2ee</artifactId>
         <version>12.0.5</version>
     </dependency>

• WAS (O, requires J2EE) - IBM WebSphere Application Server (WAS) root module.

  • Api (O) - builds specific API used to sample WAS JMX (jar). Maven dependency:

       <dependency>
           <groupId>com.jkoolcloud.tnt4j.stream</groupId>
           <artifactId>tnt4j-stream-jmx-was-api</artifactId>
           <version>12.0.5</version>
        </dependency>

  • War (O) - builds WAS compliant web application package (war). Maven dependency:

       <dependency>
           <groupId>com.jkoolcloud.tnt4j.stream</groupId>
           <artifactId>tnt4j-stream-jmx-was-war</artifactId>
           <version>12.0.5</version>
        </dependency>

  • Ear (O) - builds WAS compliant enterprise application package (ear). Maven dependency:

       <dependency>
           <groupId>com.jkoolcloud.tnt4j.stream</groupId>
           <artifactId>tnt4j-stream-jmx-was-ear</artifactId>
           <version>12.0.5</version>
        </dependency>

• Liberty (O, requires J2EE) - IBM WebSphere Liberty root module.

  • Api (O) - builds specific API used to sample Liberty JMX (jar). Maven dependency:

       <dependency>
           <groupId>com.jkoolcloud.tnt4j.stream</groupId>
           <artifactId>tnt4j-stream-jmx-liberty-api</artifactId>
           <version>12.0.5</version>
        </dependency>

  • War (O) - builds Liberty compliant web application package (war). Maven dependency:

       <dependency>
           <groupId>com.jkoolcloud.tnt4j.stream</groupId>
           <artifactId>tnt4j-stream-jmx-liberty-war</artifactId>
           <version>12.0.5</version>
        </dependency>

• ZK (O) - JMX connections resolution for VMs coordinated by ZooKeeper. Maven dependency:

     <dependency>
         <groupId>com.jkoolcloud.tnt4j.stream</groupId>
         <artifactId>tnt4j-stream-jmx-zk</artifactId>
         <version>12.0.5</version>
      </dependency>

• KRaft (O) - JMX connections resolution for VMs coordinated by Kafka KRaft. Maven dependency:

     <dependency>
         <groupId>com.jkoolcloud.tnt4j.stream</groupId>
         <artifactId>tnt4j-stream-jmx-kraft</artifactId>
         <version>12.0.5</version>
      </dependency>

• Distribution (OU) - build distribution packages. After running, see build/ directory.

All optional modules (extensions) depend on core module and can't be built and run without it.

Distribution module performs Maven post-build release assemblies delivery to build/ directory.

• JDK 17+
• Apache Maven 3
• TNT4J
• JESL

All other required dependencies are defined in project modules pom.xml files. If Maven is running online mode it should download these defined dependencies automatically.

Some of the required and optional dependencies may not be available in public Maven Repository. In this case we would recommend to download those dependencies manually into the module's lib directory and install into local Maven repository by running Maven script lib/pom.xml with install goal. For example see tnt4j-stream-jmx/tnt4j-stream-jmx-was/tnt4j-stream-jmx-was-api/lib/pom.xml to see how to do this.

This module does not require manually downloaded dependencies, but depends on JDK-contains attach instrumentation library.

• For Java versions prior to 9, dependency is defined in:

  • Maven POM script by

    <dependency>
        <groupId>com.sun</groupId>
        <artifactId>tools</artifactId>
        <version>${project.java.version}</version>
        <scope>system</scope>
        <systemPath>${java.home}/../lib/tools.jar</systemPath>
    </dependency>

  • System executables bin/stream-jmx*.bat or bin/stream-jmx*.sh by variable TOOLS_PATH

    • .bat/cmd

      set "TOOLS_PATH=%JAVA_HOME%\lib\tools.jar"

    • .sh

      TOOLS_PATH="$JAVA_HOME/lib/tools.jar"

• For Java versions 9+, jdk.attach module is enabled in:

  • Maven POM script by adding maven-compiler-plugin plugin configuration

      <compilerArgs>
          <arg>--add-exports=jdk.attach/sun.tools.attach=ALL-UNNAMED</arg>
          <arg>--add-opens=jdk.attach/sun.tools.attach=ALL-UNNAMED</arg>
      </compilerArgs>

  • System executables bin/stream-jmx*.bat or bin/stream-jmx*.sh by variable TNT4JOPTS

    • .bat/cmd

      TNT4JOPTS="--add-exports=jdk.attach/sun.tools.attach=ALL-UNNAMED" "--add-opens=jdk.attach/sun.tools.attach=ALL-UNNAMED"

    • .sh

      TNT4JOPTS="--add-exports=jdk.attach/sun.tools.attach=ALL-UNNAMED --add-opens=jdk.attach/sun.tools.attach=ALL-UNNAMED"

you may need to change paths if these do not match your environment.

Because this module requires manually downloaded libraries, it is commented out in the main project pom file tnt4j-stream-jmx/pom.xml by default. If you want to use it, uncomment this line in the pom.xml file. But WAS module will be ready to build only when manually downloaded libraries will be installed to local Maven repository.

What to download manually or copy from your existing IBM MQ installation:

• IBM WAS (e.g., version 8.5) client libs
• j2ee API library

Download the above libraries and place into the tnt4j-stream-jmx/tnt4j-stream-jmx-was/tnt4j-stream-jmx-was-api/lib directory like this:

    lib
     + was
         |- com.ibm.ws.admin.client_8.5.0.jar
         |- com.ibm.ws.ejb.thinclient_8.5.0.jar
         |- com.ibm.ws.orb_8.5.0.jar

(O) marked libraries are optional

Additionally alter system executables bin/stream-jmx*.bat or bin/stream-jmx*.sh by extending environment variable LIBPATH value:

• MS Windows

  set "WAS_HOME=C:\IBM\WebSphere\AppServer"
  set "WAS_PATH=%WAS_HOME%\runtimes\*;%WAS_HOME%\lib\webadmin\management.jar;%WAS_HOME%\plugins\com.ibm.ws.runtime.jar"
  set "LIBPATH=%RUNDIR%..\*;%RUNDIR%..\lib\*;%WAS_PATH%"

• *nix

  WAS_HOME="/opt/IBM/WebSphere/AppServer"
  WAS_PATH="$WAS_HOME/runtimes/*:$WAS_HOME/lib/webadmin/management.jar:$WAS_HOME/plugins/com.ibm.ws.runtime.jar"
  LIBPATH="$SCRIPTPATH/../*:$SCRIPTPATH/../lib/*:$WAS_PATH"

If you don't have actual WAS installation, WAS_PATH may also refer to jars located in tnt4j-stream-jmx/tnt4j-stream-jmx-was/lib/* directory.

• To build the project, run Maven goals clean package
• To build the project and install to local repo, run Maven goals clean install
• To make distributable release assemblies use one of profiles: pack-assembly and pack-sources-and-javadocs:
  • containing only binary (including test package) distribution: run mvn -P pack-assembly
  • containing binary (including test package), source and javadoc distribution: run mvn -P pack-sources-and-javadocs,pack-assembly
• To make Maven required source and javadoc packages, use profile pack-sources-and-javadocs
• To make Maven central compliant release having source, javadoc and all signed packages, use final-release profile

By default, Maven will build all modules defined in tnt4j-stream-jmx/pom.xml file.

If you do not want to build some of optional modules, comment those out like WAS module is. Or you can define Maven to build your preferred set of modules using -pl, --projects argument (comma separated modules list) together with -am, --also-make argument, e.g.:

mvn -pl tnt4j-stream-jmx-core,tnt4j-stream-jmx--distribution -am clean install -P pack-assembly

or

mvn --projects tnt4j-stream-jmx-core,tnt4j-stream-jmx--distribution --also-make clean install -P pack-assembly

The modules list should not contain spaces after commas!

Issuing these commands, Maven will build only tnt4j-stream-jmx-core and tnt4j-stream-jmx--distribution modules.

Release assemblies are built in the build/ directory.

Sometimes Maven fails to correctly handle dependencies. If dependency configuration looks fine, but Maven still complains about missing dependencies, try to delete local Maven repository by hand: e.g., on MS Windows delete contents of c:\Users\[username]\.m2\repository directory.

See Using Stream-JMX section.