Feat: Let user specify a user agent prefix

This patch exposes an option in `SessionOptions` that a user can set,
which will be prefixed to the beginning of the user agent sent to the
broker during session negotiation.  This prefix does not need to be
set, but if it is, it must consist only of printable ASCII characters
and must be less than 128 characters long.

Signed-off-by: Patrick M. Niedzielski <[email protected]>

Author: pniedzielski

bmq-sdk/src/main/java/com/bloomberg/bmq/SessionOptions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Bloomberg Finance L.P.
+ * Copyright 2022-2025 Bloomberg Finance L.P.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -62,6 +62,10 @@
  *       HostHealthMonitor} interface responsible for notifying the session when the health of the
  *       host machine has changed. A {@code hostHealthMonitor} must be specified in oder for queues
  *       opened through the session to suspend on unhealthy hosts.
+ *   <li>{@code userAgentPrefix}: String to include in the user agent for broker telemetry. This
+ *       string must only contain printable characters and must be less than 128 characters long.
+ *       This is provided for libraries that are wrapping this SDK. Applications directly using the
+ *       SDK are encouraged <strong>NOT</strong> to set this value.
  * </ul>
  *
  * <H2>Thread Safety</H2>
@@ -215,6 +219,8 @@ public int highWaterMark() {
 
     private final HostHealthMonitor hostHealthMonitor;
 
+    private final String userAgentPrefix;
+
     private SessionOptions() {
         brokerUri = DEFAULT_URI;
         startTimeout = DEFAULT_START_TIMEOUT;
@@ -226,6 +232,7 @@ private SessionOptions() {
         configureQueueTimeout = QUEUE_OPERATION_TIMEOUT;
         closeQueueTimeout = QUEUE_OPERATION_TIMEOUT;
         hostHealthMonitor = null;
+        userAgentPrefix = "";
     }
 
     private SessionOptions(Builder builder) {
@@ -239,6 +246,7 @@ private SessionOptions(Builder builder) {
         configureQueueTimeout = builder.configureQueueTimeout;
         closeQueueTimeout = builder.closeQueueTimeout;
         hostHealthMonitor = builder.hostHealthMonitor;
+        userAgentPrefix = builder.userAgentPrefix;
     }
 
     /**
@@ -383,6 +391,16 @@ public HostHealthMonitor hostHealthMonitor() {
         return hostHealthMonitor;
     }
 
+    /**
+     * Returns the string that will be prefixed to the user agent used by {@link
+     * com.bloomberg.bmq.Session} to identify itself to the broker.
+     *
+     * @return String user agent string prefix
+     */
+    public String userAgentPrefix() {
+        return userAgentPrefix;
+    }
+
     /** Helper class to create a {@code SesssionOptions} object with custom settings. */
     public static class Builder {
         private URI brokerUri;
@@ -397,6 +415,9 @@ public static class Builder {
         private Duration closeQueueTimeout;
 
         private HostHealthMonitor hostHealthMonitor;
+
+        private String userAgentPrefix;
+
         /**
          * Creates a {@code SesssionOptions} object based on this {@code Builder} properties.
          *
@@ -417,6 +438,7 @@ private Builder(SessionOptions options) {
             configureQueueTimeout = options.configureQueueTimeout;
             closeQueueTimeout = options.closeQueueTimeout;
             hostHealthMonitor = options.hostHealthMonitor;
+            userAgentPrefix = options.userAgentPrefix;
         }
 
         /**
@@ -558,5 +580,29 @@ public Builder setHostHealthMonitor(HostHealthMonitor value) {
             hostHealthMonitor = Argument.expectNonNull(value, "host health monitor");
             return this;
         }
+
+        /**
+         * Sets the user agent prefix. This string is prefixed to a user agent constructed by the
+         * SDK. This is intended ONLY for other libraries that wrap this SDK to identify themselves
+         * for broker telemetry. Applications that are directly using this SDK are encouraged not
+         * to set this.
+         *
+         * @param value String user agent prefix
+         * @return Builder this object
+         * @throws NullPointerException if the specified value is null
+         * @throws IllegalArgumentException in case the specified value contains non-ASCII
+         *     characters, contains non-printable characters (i.e., control characters), or is
+         *     longer than 127 characters.
+         */
+        public Builder setUserAgentPrefix(String value) {
+            Argument.expectNonNull(value, "user agent prefix");
+            Argument.expectCondition(
+                    value.codePoints().allMatch(c -> c < 128 && !Character.isISOControl(c)),
+                    "user agent prefix must be printable ASCII");
+            Argument.expectCondition(
+                    value.length() < 128, "user agent prefix must be shorter than 128 characters");
+            userAgentPrefix = value;
+            return this;
+        }
     }
 }

bmq-sdk/src/main/java/com/bloomberg/bmq/impl/TcpBrokerConnection.java

@@ -378,9 +378,13 @@ private NegotiationMessageChoice createNegoMsg() {
     }
 
     private String constructUserAgent() {
+        String prefix = "";
+        if (connectionOptions.userAgentPrefix().length() > 0) {
+            prefix = connectionOptions.userAgentPrefix() + " ";
+        }
         String javaVersion = "java" + SystemUtil.getJavaVersionString();
         String sdkVersion = VersionUtil.getJarVersion();
-        return "com.bloomberg.bmq(" + javaVersion + "):" + sdkVersion;
+        return prefix + "com.bloomberg.bmq(" + javaVersion + "):" + sdkVersion;
     }
 
     private WriteStatus negotiate() throws IOException {

bmq-sdk/src/main/java/com/bloomberg/bmq/impl/infr/net/ConnectionOptions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2022 Bloomberg Finance L.P.
+ * Copyright 2022-2025 Bloomberg Finance L.P.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -39,12 +39,14 @@ public final class ConnectionOptions {
     private int startNumRetries = DEFAULT_START_NUM_RETRIES;
     private Duration startRetryInterval = DEFAULT_START_RETRY_INTERVAL;
     private WriteBufferWaterMark writeWaterMark = new WriteBufferWaterMark();
+    private String userAgentPrefix = "";
 
     public ConnectionOptions() {}
 
     public ConnectionOptions(SessionOptions sesOpts) {
         brokerUri = sesOpts.brokerUri();
         writeWaterMark = sesOpts.writeBufferWaterMark();
+        userAgentPrefix = sesOpts.userAgentPrefix();
     }
 
     public ConnectionOptions setBrokerUri(URI value) {
@@ -80,6 +82,17 @@ public ConnectionOptions setWriteBufferWaterMark(WriteBufferWaterMark value) {
         return this;
     }
 
+    public ConnectionOptions setUserAgentPrefix(String value) {
+        Argument.expectNonNull(value, "user agent prefix");
+        Argument.expectCondition(
+                value.codePoints().allMatch(c -> c < 128 && !Character.isISOControl(c)),
+                "user agent prefix must be printable ASCII");
+        Argument.expectCondition(
+                value.length() < 128, "user agent prefix must be shorter than 128 characters");
+        userAgentPrefix = value;
+        return this;
+    }
+
     public URI brokerUri() {
         return brokerUri;
     }
@@ -99,4 +112,8 @@ public Duration startRetryInterval() {
     public WriteBufferWaterMark writeBufferWaterMark() {
         return writeWaterMark;
     }
+
+    public String userAgentPrefix() {
+        return userAgentPrefix;
+    }
 }