fix(client/java): correct browseChildrenRaw README; CLI --require-certificate-validation (Client.Java-037,038)

clients/java/README.md

@@ -128,18 +128,20 @@ gradle :zb-mom-ww-mxgateway-cli:run --args="galaxy-discover --endpoint localhost
 
 ### Browsing lazily
 
-For UI trees or OPC UA bridges, use `browseChildren` to walk one level at a
+For UI trees or OPC UA bridges, use `browseChildrenRaw` to walk one level at a
 time instead of loading the full hierarchy with `discoverHierarchy`. Pass a
 default request for root objects; subsequent calls set `parentGobjectId`,
 `parentTagName`, or `parentContainedPath`. Filter fields match
 `DiscoverHierarchy`. Each response pairs `getChildrenList()` with
 `getChildHasChildrenList()` so you know which nodes to expand. See
 [Galaxy Repository](../../docs/GalaxyRepository.md#browsechildren) for full
-request and filter semantics. This snippet documents the API as it appears once
-the Java client is regenerated on the Windows host.
+request and filter semantics. For most callers the high-level
+`browse()`/`LazyBrowseNode` walker below is the preferred surface;
+`browseChildrenRaw` exposes the single underlying RPC when you need direct
+control of paging.
 
 ```java
-BrowseChildrenReply reply = galaxy.browseChildren(
+BrowseChildrenReply reply = galaxy.browseChildrenRaw(
         BrowseChildrenRequest.newBuilder().build());
 
 List<GalaxyObject> children = reply.getChildrenList();
@@ -248,8 +250,11 @@ gradle :zb-mom-ww-mxgateway-cli:run --args="smoke --endpoint localhost:5000 --ap
 ```
 
 The CLI accepts `--api-key`, `--api-key-env`, `--plaintext`, `--ca-file`,
-`--server-name-override`, `--timeout`, and `--json` on gateway commands. JSON
-output redacts API keys.
+`--server-name-override`, `--require-certificate-validation`, `--timeout`, and
+`--json` on gateway commands. JSON output redacts API keys. TLS is lenient by
+default (the certificate is not verified unless you pin a CA with `--ca-file`);
+pass `--require-certificate-validation` to verify the server certificate against
+the JVM trust store without pinning.
 
 Use TLS options for a secured gateway:
 

clients/java/zb-mom-ww-mxgateway-cli/src/main/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCli.java

@@ -1366,6 +1366,13 @@ public final class MxGatewayCli implements Callable<Integer> {
         @Option(names = "--server-name-override", description = "TLS server name override.")
         String serverNameOverride = "";
 
+        @Option(
+                names = "--require-certificate-validation",
+                description =
+                        "Verify the server certificate against the JVM trust store "
+                                + "(disables the lenient default; ignored with --plaintext or --ca-file pinning).")
+        boolean requireCertificateValidation;
+
         @Option(names = "--timeout", defaultValue = "30s", description = "Per-call timeout.")
         String timeout;
 
@@ -1388,6 +1395,7 @@ public final class MxGatewayCli implements Callable<Integer> {
                     .plaintext(plaintext)
                     .caCertificatePath(caFile)
                     .serverNameOverride(serverNameOverride)
+                    .requireCertificateValidation(requireCertificateValidation)
                     .callTimeout(resolvedTimeout)
                     .build();
         }
@@ -1400,6 +1408,7 @@ public final class MxGatewayCli implements Callable<Integer> {
             values.put("plaintext", plaintext);
             values.put("caFile", caFile == null ? "" : caFile.toString());
             values.put("serverNameOverride", serverNameOverride);
+            values.put("requireCertificateValidation", requireCertificateValidation);
             values.put("timeout", timeout);
             return values;
         }

clients/java/zb-mom-ww-mxgateway-cli/src/test/java/com/zb/mom/ww/mxgateway/cli/MxGatewayCliTests.java

@@ -5,6 +5,7 @@ import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import com.zb.mom.ww.mxgateway.client.MxGatewayAlarmFeedSubscription;
+import com.zb.mom.ww.mxgateway.client.MxGatewayClientOptions;
 import io.grpc.stub.StreamObserver;
 import java.io.ByteArrayInputStream;
 import java.io.InputStream;
@@ -289,6 +290,51 @@ final class MxGatewayCliTests {
         }
     }
 
+    @Test
+    void requireCertificateValidationFlagPropagatesThroughToClientOptions() {
+        // Client.Java-038 regression — the --require-certificate-validation
+        // CLI flag must reach MxGatewayClientOptions.requireCertificateValidation
+        // via CommonOptions.toClientOptions(), so CLI users can opt into strict
+        // JVM-trust verification without pinning a CA.
+        CapturingClientFactory factory = new CapturingClientFactory();
+        CliRun run = execute(
+                factory,
+                "acknowledge-alarm",
+                "--endpoint",
+                "localhost:5000",
+                "--api-key-env",
+                "MXGATEWAY_API_KEY",
+                "--require-certificate-validation",
+                "--reference",
+                "Tank01.Level.HiHi");
+
+        assertEquals(0, run.exitCode(), "errors:\n" + run.errors());
+        assertTrue(
+                factory.capturedClientOptions.requireCertificateValidation(),
+                "--require-certificate-validation did not propagate into MxGatewayClientOptions");
+    }
+
+    @Test
+    void requireCertificateValidationDefaultsToLenientWhenFlagAbsent() {
+        // Without the flag, the lenient-by-default trust posture must be
+        // preserved (requireCertificateValidation == false).
+        CapturingClientFactory factory = new CapturingClientFactory();
+        CliRun run = execute(
+                factory,
+                "acknowledge-alarm",
+                "--endpoint",
+                "localhost:5000",
+                "--api-key-env",
+                "MXGATEWAY_API_KEY",
+                "--reference",
+                "Tank01.Level.HiHi");
+
+        assertEquals(0, run.exitCode(), "errors:\n" + run.errors());
+        assertFalse(
+                factory.capturedClientOptions.requireCertificateValidation(),
+                "requireCertificateValidation should default to false (lenient)");
+    }
+
     @Test
     void streamAlarmsCommandFailsFastOnQueueOverflow() {
         // Client.Java-033 regression — the CLI's stream-alarms bounded queue
@@ -435,6 +481,23 @@ final class MxGatewayCliTests {
         }
     }
 
+    /**
+     * Factory that records the {@link MxGatewayClientOptions} produced by
+     * {@link MxGatewayCli.CommonOptions#toClientOptions()} so a test can assert
+     * how CLI flags map onto the library option surface. Wraps the standard
+     * {@link FakeClient} so the command body still completes. Used by the
+     * Client.Java-038 option-flow regression.
+     */
+    private static final class CapturingClientFactory implements MxGatewayCli.MxGatewayCliClientFactory {
+        private MxGatewayClientOptions capturedClientOptions;
+
+        @Override
+        public MxGatewayCli.MxGatewayCliClient connect(MxGatewayCli.CommonOptions options) {
+            capturedClientOptions = options.toClientOptions();
+            return new FakeClient(options.spec.commandLine().getOut());
+        }
+    }
+
     /**
      * Factory whose fake client floods the {@code streamAlarms} observer with
      * 2000 messages synchronously, exceeding the CLI's bounded 1024-element