TNT4J-Streams-WGS

TNT4J Streams for handling WGS-subscribed events/messages.

TNT4J-Streams-WGS is under Nastel Technologies EULA.

TNT4J-Streams-WGS is extension of TNT4J-Streams that provides the ability to stream WGS-subscribed events/messages as activity events to XRay/Track.

This document covers only information specific to the TNT4J-Streams-WGS project. See TNT4J-Streams for more details.

Allows streaming activities parsed from WGS-subscribed event data.

• Select File->Import...->Maven->Existing Maven Projects
• Click 'Next'
• In the 'Root directory' field, select the path of the directory where you downloaded the TNT4J-Streams project
• Click 'OK'
• Dialog fills in with project modules details
• Click 'Finish'

Also see TNT4J-Streams document Running TNT4J-Streams.

• As a standalone application
  • Write the streams configuration file. See the Streams configuration chapter for more details.
  • Configure your loggers

  • Run the standalone application using:

• bin/tnt4j-streams.bat (Windows)

• bin/tnt4j-streams.sh (Linux/macOS)

• As an API integrated into your product.

  • Use the following Maven dependency:

    <dependency>
        <groupId>com.jkoolcloud.tnt4j.streams</groupId>
        <artifactId>tnt4j-streams-wgs</artifactId>
        <version>12.0.0</version>
    </dependency>

  • Write the streams configuration file. See the Streams configuration for more details.

  • Call the API in your code:

    StreamsAgent.runFromAPI(new CfgStreamsBuilder().setConfig(configFileName));

When release assemblies are built, samples are located in the samples directory (e.g., build/tnt4j-streams-wgs-12.0.0/samples). To run a sample:

1. Go to the sample directory.

2. Run run.bat or run.sh depending on your OS.

For a more detailed explanation of stream and parser configuration and usage, see Configuring TNT4J-Streams-WGS and the JavaDocs.

This sample shows how to stream activity events from WGS-subscribed statistics events.

• Sample files can be found in the samples/wgs-statistics-events directory.

• See the sample IBM MQ Statistics Events Provided by meshIQ WGS Streaming over TNT4J for more details.

See TNT4J-Streams for more details on related configuration.

• Host — WGS host name/IP. In addition, it supports the WMQ connection formats HOST(PORT) and HOST:PORT. Also can have multiple values delimited using , symbol. (Required)

• Port — WGS port number. Default: 4010. (Optional)

• UserName — WGS authentication user name. (Optional)

• Password — WGS user password. (Optional)

• StreamReconnectDelay — Delay in seconds before WGS reconnection after communication failure. Default: 10 sec. (Optional)

• ConnectTimeoutMs — WGS connection timeout in milliseconds. 0 means infinite timeout. Default: 30000 (30 sec). (Optional)

• MsgReadTimeoutMs — WGS message read timeout in milliseconds. 0 means infinite timeout. Default: 10000 (10 sec). (Optional)

• Set of PCF parameters used to configure WGS events subscription (Optional):

• NEXCMD.EXCA_MANAGER_NAME — WGS group manager name. Default: MQM.

• NEXCMD.EXIA_MON_MSG_TYPE — WGS events to subscribe. Default: NEXCMD.EXMONT_STAT_MQI | NEXCMD.EXMONT_STAT_Q | NEXCMD.EXMONT_STAT_CHL

• FILTER.* — Set of filter definitions. Patterns are like these: FILTER.[INCLUDE/EXCLUDE].[ATTR_NAME] or FILTER.[INCLUDE/EXCLUDE] (this one requires a matcher expression referencing message attributes). The value of the property can be a set of values such as VAL01[|VAL02|VAL03|VAL04|VAL05|VAL06] or any matcher expression like groovy:$fieldValue >= 800 && $fieldValue < 930 or groovy:${MQIA_COMMAND_LEVEL} >= 800 && ${MQIA_COMMAND_LEVEL} < 930. (Optional)

Configuration sample:

<property name="Host" value="127.0.0.1"/>
<property name="Port" value="4010"/>
<property name="UserName" value="SecretUser"/>
<property name="Password" value="xRNw9FvRtCk="/>
<property name="StreamReconnectDelay" value="15"/>
<property name="ConnectTimeoutMs" value="15000"/>
<property name="MsgReadTimeoutMs" value="5000"/>
<property name="NEXCMD.EXCA_MANAGER_NAME" value="MQM"/>
<property name="NEXCMD.EXIA_MON_MSG_TYPE" value="NEXCMD.EXMONT_STAT_MQI | NEXCMD.EXMONT_STAT_Q | NEXCMD.EXMONT_STAT_CHL"/>
<!-- Events filtering to narrow scope -->
<property name="FILTER.INCLUDE.MQCA_Q_MGR_NAME" value="GPBTDL01|RPITDL01|RPITDL02|SRSTW210|SRSTW207|SQATDW23"/>
<property name="FILTER.INCLUDE.MQIA_COMMAND_LEVEL"><![CDATA[
    groovy:$fieldValue >= 800 && $fieldValue < 930
]]></property>
<property name="FILTER.INCLUDE"><![CDATA[
    groovy:${MQIA_COMMAND_LEVEL} >= 800 && ${MQIA_COMMAND_LEVEL} < 930
]]></property>

Also see Generic streams parameters and Buffered streams parameters.

• TranslateNumValues — Indicates that the parser should translate resolved numeric values to corresponding MQ constant names if possible, and the field/locator data type is String (meaning the translated value can be assigned to the field). If the value of a particular field should be left as a number (e.g., ReasonCode), use field/locator attribute datatype="Number". Default: true. (Optional)

Configuration sample:

<property name="TranslateNumValues" value="false"/>

Also see Generic parser parameters.

• JDK 17+
• Apache Maven 3
• TNT4J-Streams core module in particular

All other required dependencies are defined in the project pom.xml file located at <tnt4j-streams-wgs>/pom.xml. If Maven is running in online mode, it will automatically download the defined dependencies.

If you have build and installed TNT4J-Streams into your local Maven repository, you don't need to install it manually.

TNT4J-Streams-WGS project does not require any manually downloaded dependencies at the moment.

Also see TNT4J-Streams README document chapter Manually installed dependencies

• 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 the profiles: pack-assembly and pack-sources-and-javadocs:

  • Binary (including test package) distribution:
    mvn -P pack-assembly

  • Binary (including test package), source, and javadoc distribution:
    mvn -P pack-sources-and-javadocs,pack-assembly

• To make the Maven-required source and javadoc packages, use the profile: pack-sources-and-javadocs

• To make a Maven Central–compliant release having source, javadoc, and all signed packages, use the profile: final-release

• Release assemblies are built to the build/ directory.

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

To summarize, the quick "how to build" steps are as follows:

1. If tnt4j-streams has not been built yet, build it: run mvn clean install for a pom.xml file located in tnt4j-streams directory.
2. Now you can build tnt4j-streams-wgs: run mvn clean install for a pom.xml file located in tnt4j-streams-wgs directory.

See Running TNT4J-Streams-WGS for more details.

• JUnit 4
• Mockito

Maven test runs are disabled by default. To enable Maven to run tests, set the Maven command-line argument -DskipTests=false or use profile run-tests.

In the wgs module, run the JUnit test suite named AllWGSStreamTests