Issue #47: scaffold Java Gradle build

Issue #44: implement Rust client session values errors and CLI

clients/java/README.md

@@ -0,0 +1,41 @@
+# Java Client
+
+The Java client workspace contains the Gradle scaffold for the MXAccess Gateway
+client library, generated protobuf/gRPC bindings, a test CLI project, and JUnit
+tests.
+
+## Layout
+
+```text
+clients/java/
+  settings.gradle
+  build.gradle
+  src/main/generated/
+  mxgateway-client/
+  mxgateway-cli/
+```
+
+`mxgateway-client` generates Java protobuf and gRPC sources from
+`../../src/MxGateway.Contracts/Protos`. The Gradle protobuf plugin writes those
+generated sources under `src/main/generated`, which matches the client proto
+manifest in `../proto/proto-inputs.json`. Do not edit generated files by hand.
+
+`mxgateway-cli` depends on `mxgateway-client` and provides the `mxgw-java`
+application entry point used by later CLI implementation work.
+
+## Build And Test
+
+Run the Java checks from `clients/java`:
+
+```powershell
+gradle test
+```
+
+The build uses the Java 21 Gradle toolchain, compiles generated protobuf/gRPC
+code, and runs JUnit 5 tests for the scaffold and CLI entry point.
+
+## Related Documentation
+
+- [Client Proto Generation](../../docs/client-proto-generation.md)
+- [Java Client Detailed Design](../../docs/clients-java-design.md)
+- [Java Style Guide](../../docs/style-guides/JavaStyleGuide.md)

clients/java/build.gradle

@@ -0,0 +1,38 @@
+plugins {
+    id 'base'
+}
+
+ext {
+    grpcVersion = '1.76.0'
+    junitVersion = '5.14.1'
+    picocliVersion = '4.7.7'
+    protobufVersion = '4.33.1'
+}
+
+subprojects {
+    group = 'com.dohertylan.mxgateway'
+    version = '0.1.0'
+
+    pluginManager.withPlugin('java') {
+        java {
+            toolchain {
+                languageVersion = JavaLanguageVersion.of(21)
+            }
+        }
+
+        tasks.withType(JavaCompile).configureEach {
+            options.encoding = 'UTF-8'
+            options.release = 21
+        }
+
+        tasks.withType(Test).configureEach {
+            useJUnitPlatform()
+        }
+
+        dependencies {
+            testImplementation platform("org.junit:junit-bom:${junitVersion}")
+            testImplementation 'org.junit.jupiter:junit-jupiter'
+            testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
+        }
+    }
+}

clients/java/mxgateway-cli/build.gradle

@@ -0,0 +1,12 @@
+plugins {
+    id 'application'
+}
+
+dependencies {
+    implementation project(':mxgateway-client')
+    implementation "info.picocli:picocli:${picocliVersion}"
+}
+
+application {
+    mainClass = 'com.dohertylan.mxgateway.cli.MxGatewayCli'
+}

clients/java/mxgateway-cli/src/main/java/com/dohertylan/mxgateway/cli/MxGatewayCli.java

@@ -0,0 +1,53 @@
+package com.dohertylan.mxgateway.cli;
+
+import com.dohertylan.mxgateway.client.MxGatewayClientVersion;
+import java.io.PrintWriter;
+import java.util.concurrent.Callable;
+import picocli.CommandLine;
+import picocli.CommandLine.Command;
+import picocli.CommandLine.Model.CommandSpec;
+import picocli.CommandLine.Spec;
+
+@Command(
+        name = "mxgw-java",
+        mixinStandardHelpOptions = true,
+        description = "MXAccess Gateway Java test CLI.",
+        subcommands = MxGatewayCli.VersionCommand.class)
+public final class MxGatewayCli implements Callable<Integer> {
+    @Spec
+    private CommandSpec spec;
+
+    public static void main(String[] args) {
+        int exitCode = new CommandLine(new MxGatewayCli()).execute(args);
+        System.exit(exitCode);
+    }
+
+    public static int execute(PrintWriter out, PrintWriter err, String... args) {
+        CommandLine commandLine = new CommandLine(new MxGatewayCli());
+        commandLine.setOut(out);
+        commandLine.setErr(err);
+        return commandLine.execute(args);
+    }
+
+    @Override
+    public Integer call() {
+        spec.commandLine().usage(spec.commandLine().getOut());
+        return 0;
+    }
+
+    @Command(name = "version", description = "Prints the Java client scaffold version.")
+    public static final class VersionCommand implements Callable<Integer> {
+        @Spec
+        private CommandSpec spec;
+
+        @Override
+        public Integer call() {
+            spec.commandLine().getOut().printf(
+                    "mxgateway-java %s gatewayProtocolVersion=%d workerProtocolVersion=%d%n",
+                    MxGatewayClientVersion.clientVersion(),
+                    MxGatewayClientVersion.gatewayProtocolVersion(),
+                    MxGatewayClientVersion.workerProtocolVersion());
+            return 0;
+        }
+    }
+}

clients/java/mxgateway-cli/src/test/java/com/dohertylan/mxgateway/cli/MxGatewayCliTests.java

@@ -0,0 +1,27 @@
+package com.dohertylan.mxgateway.cli;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import java.io.PrintWriter;
+import java.io.StringWriter;
+import org.junit.jupiter.api.Test;
+
+final class MxGatewayCliTests {
+    @Test
+    void versionCommandPrintsProtocolVersions() {
+        StringWriter output = new StringWriter();
+        StringWriter errors = new StringWriter();
+
+        int exitCode = MxGatewayCli.execute(
+                new PrintWriter(output, true),
+                new PrintWriter(errors, true),
+                "version");
+
+        assertEquals(0, exitCode);
+        assertEquals("", errors.toString());
+        assertTrue(output.toString().contains("mxgateway-java 0.1.0"));
+        assertTrue(output.toString().contains("gatewayProtocolVersion=1"));
+        assertTrue(output.toString().contains("workerProtocolVersion=1"));
+    }
+}

clients/java/mxgateway-client/build.gradle

@@ -0,0 +1,46 @@
+plugins {
+    id 'java-library'
+    id 'com.google.protobuf'
+}
+
+dependencies {
+    api "com.google.protobuf:protobuf-java:${protobufVersion}"
+    api "io.grpc:grpc-protobuf:${grpcVersion}"
+    api "io.grpc:grpc-stub:${grpcVersion}"
+
+    implementation "io.grpc:grpc-netty-shaded:${grpcVersion}"
+
+    compileOnly 'javax.annotation:javax.annotation-api:1.3.2'
+}
+
+sourceSets {
+    main {
+        proto {
+            srcDir rootProject.file('../../src/MxGateway.Contracts/Protos')
+            include 'mxaccess_gateway.proto'
+            include 'mxaccess_worker.proto'
+        }
+    }
+}
+
+protobuf {
+    protoc {
+        artifact = "com.google.protobuf:protoc:${protobufVersion}"
+    }
+
+    plugins {
+        grpc {
+            artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}"
+        }
+    }
+
+    generatedFilesBaseDir = rootProject.file('src/main/generated').absolutePath
+
+    generateProtoTasks {
+        all().configureEach {
+            plugins {
+                grpc {}
+            }
+        }
+    }
+}

clients/java/mxgateway-client/src/main/java/com/dohertylan/mxgateway/client/MxGatewayClientVersion.java

@@ -0,0 +1,22 @@
+package com.dohertylan.mxgateway.client;
+
+public final class MxGatewayClientVersion {
+    private static final int GATEWAY_PROTOCOL_VERSION = 1;
+    private static final int WORKER_PROTOCOL_VERSION = 1;
+    private static final String CLIENT_VERSION = "0.1.0";
+
+    private MxGatewayClientVersion() {
+    }
+
+    public static String clientVersion() {
+        return CLIENT_VERSION;
+    }
+
+    public static int gatewayProtocolVersion() {
+        return GATEWAY_PROTOCOL_VERSION;
+    }
+
+    public static int workerProtocolVersion() {
+        return WORKER_PROTOCOL_VERSION;
+    }
+}

clients/java/mxgateway-client/src/test/java/com/dohertylan/mxgateway/client/GeneratedContractSmokeTests.java

@@ -0,0 +1,29 @@
+package com.dohertylan.mxgateway.client;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import mxaccess_gateway.v1.MxAccessGatewayGrpc;
+import mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest;
+import mxaccess_worker.v1.MxaccessWorker.WorkerEnvelope;
+import org.junit.jupiter.api.Test;
+
+final class GeneratedContractSmokeTests {
+    @Test
+    void generatedGatewayAndWorkerContractsCompile() {
+        OpenSessionRequest request = OpenSessionRequest.newBuilder()
+                .setClientSessionName("junit")
+                .build();
+        WorkerEnvelope envelope = WorkerEnvelope.newBuilder()
+                .setProtocolVersion(MxGatewayClientVersion.workerProtocolVersion())
+                .build();
+
+        assertEquals("junit", request.getClientSessionName());
+        assertEquals("mxaccess_gateway.v1.MxAccessGateway", MxAccessGatewayGrpc.SERVICE_NAME);
+        assertEquals(1, envelope.getProtocolVersion());
+    }
+
+    @Test
+    void javaTwentyOneToolchainRunsTests() {
+        assertEquals(21, Runtime.version().feature());
+    }
+}

clients/java/settings.gradle

@@ -0,0 +1,22 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        mavenCentral()
+    }
+
+    plugins {
+        id 'com.google.protobuf' version '0.9.5'
+    }
+}
+
+dependencyResolutionManagement {
+    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
+    repositories {
+        mavenCentral()
+    }
+}
+
+rootProject.name = 'mxaccessgw-java'
+
+include 'mxgateway-client'
+include 'mxgateway-cli'

clients/java/src/main/generated/main/grpc/mxaccess_gateway/v1/MxAccessGatewayGrpc.java

@@ -0,0 +1,588 @@
+package mxaccess_gateway.v1;
+
+import static io.grpc.MethodDescriptor.generateFullMethodName;
+
+/**
+ * <pre>
+ * Public client API for MXAccess sessions hosted by the gateway.
+ * </pre>
+ */
+@io.grpc.stub.annotations.GrpcGenerated
+public final class MxAccessGatewayGrpc {
+
+  private MxAccessGatewayGrpc() {}
+
+  public static final java.lang.String SERVICE_NAME = "mxaccess_gateway.v1.MxAccessGateway";
+
+  // Static method descriptors that strictly reflect the proto.
+  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest,
+      mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply> getOpenSessionMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "OpenSession",
+      requestType = mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest.class,
+      responseType = mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
+  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest,
+      mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply> getOpenSessionMethod() {
+    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest, mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply> getOpenSessionMethod;
+    if ((getOpenSessionMethod = MxAccessGatewayGrpc.getOpenSessionMethod) == null) {
+      synchronized (MxAccessGatewayGrpc.class) {
+        if ((getOpenSessionMethod = MxAccessGatewayGrpc.getOpenSessionMethod) == null) {
+          MxAccessGatewayGrpc.getOpenSessionMethod = getOpenSessionMethod =
+              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest, mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.UNARY)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "OpenSession"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply.getDefaultInstance()))
+              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("OpenSession"))
+              .build();
+        }
+      }
+    }
+    return getOpenSessionMethod;
+  }
+
+  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest,
+      mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply> getCloseSessionMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "CloseSession",
+      requestType = mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest.class,
+      responseType = mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
+  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest,
+      mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply> getCloseSessionMethod() {
+    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest, mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply> getCloseSessionMethod;
+    if ((getCloseSessionMethod = MxAccessGatewayGrpc.getCloseSessionMethod) == null) {
+      synchronized (MxAccessGatewayGrpc.class) {
+        if ((getCloseSessionMethod = MxAccessGatewayGrpc.getCloseSessionMethod) == null) {
+          MxAccessGatewayGrpc.getCloseSessionMethod = getCloseSessionMethod =
+              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest, mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.UNARY)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "CloseSession"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply.getDefaultInstance()))
+              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("CloseSession"))
+              .build();
+        }
+      }
+    }
+    return getCloseSessionMethod;
+  }
+
+  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest,
+      mxaccess_gateway.v1.MxaccessGateway.MxCommandReply> getInvokeMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "Invoke",
+      requestType = mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest.class,
+      responseType = mxaccess_gateway.v1.MxaccessGateway.MxCommandReply.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.UNARY)
+  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest,
+      mxaccess_gateway.v1.MxaccessGateway.MxCommandReply> getInvokeMethod() {
+    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest, mxaccess_gateway.v1.MxaccessGateway.MxCommandReply> getInvokeMethod;
+    if ((getInvokeMethod = MxAccessGatewayGrpc.getInvokeMethod) == null) {
+      synchronized (MxAccessGatewayGrpc.class) {
+        if ((getInvokeMethod = MxAccessGatewayGrpc.getInvokeMethod) == null) {
+          MxAccessGatewayGrpc.getInvokeMethod = getInvokeMethod =
+              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest, mxaccess_gateway.v1.MxaccessGateway.MxCommandReply>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.UNARY)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "Invoke"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.MxCommandReply.getDefaultInstance()))
+              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("Invoke"))
+              .build();
+        }
+      }
+    }
+    return getInvokeMethod;
+  }
+
+  private static volatile io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest,
+      mxaccess_gateway.v1.MxaccessGateway.MxEvent> getStreamEventsMethod;
+
+  @io.grpc.stub.annotations.RpcMethod(
+      fullMethodName = SERVICE_NAME + '/' + "StreamEvents",
+      requestType = mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest.class,
+      responseType = mxaccess_gateway.v1.MxaccessGateway.MxEvent.class,
+      methodType = io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
+  public static io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest,
+      mxaccess_gateway.v1.MxaccessGateway.MxEvent> getStreamEventsMethod() {
+    io.grpc.MethodDescriptor<mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest, mxaccess_gateway.v1.MxaccessGateway.MxEvent> getStreamEventsMethod;
+    if ((getStreamEventsMethod = MxAccessGatewayGrpc.getStreamEventsMethod) == null) {
+      synchronized (MxAccessGatewayGrpc.class) {
+        if ((getStreamEventsMethod = MxAccessGatewayGrpc.getStreamEventsMethod) == null) {
+          MxAccessGatewayGrpc.getStreamEventsMethod = getStreamEventsMethod =
+              io.grpc.MethodDescriptor.<mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest, mxaccess_gateway.v1.MxaccessGateway.MxEvent>newBuilder()
+              .setType(io.grpc.MethodDescriptor.MethodType.SERVER_STREAMING)
+              .setFullMethodName(generateFullMethodName(SERVICE_NAME, "StreamEvents"))
+              .setSampledToLocalTracing(true)
+              .setRequestMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest.getDefaultInstance()))
+              .setResponseMarshaller(io.grpc.protobuf.ProtoUtils.marshaller(
+                  mxaccess_gateway.v1.MxaccessGateway.MxEvent.getDefaultInstance()))
+              .setSchemaDescriptor(new MxAccessGatewayMethodDescriptorSupplier("StreamEvents"))
+              .build();
+        }
+      }
+    }
+    return getStreamEventsMethod;
+  }
+
+  /**
+   * Creates a new async stub that supports all call types for the service
+   */
+  public static MxAccessGatewayStub newStub(io.grpc.Channel channel) {
+    io.grpc.stub.AbstractStub.StubFactory<MxAccessGatewayStub> factory =
+      new io.grpc.stub.AbstractStub.StubFactory<MxAccessGatewayStub>() {
+        @java.lang.Override
+        public MxAccessGatewayStub newStub(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+          return new MxAccessGatewayStub(channel, callOptions);
+        }
+      };
+    return MxAccessGatewayStub.newStub(factory, channel);
+  }
+
+  /**
+   * Creates a new blocking-style stub that supports all types of calls on the service
+   */
+  public static MxAccessGatewayBlockingV2Stub newBlockingV2Stub(
+      io.grpc.Channel channel) {
+    io.grpc.stub.AbstractStub.StubFactory<MxAccessGatewayBlockingV2Stub> factory =
+      new io.grpc.stub.AbstractStub.StubFactory<MxAccessGatewayBlockingV2Stub>() {
+        @java.lang.Override
+        public MxAccessGatewayBlockingV2Stub newStub(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+          return new MxAccessGatewayBlockingV2Stub(channel, callOptions);
+        }
+      };
+    return MxAccessGatewayBlockingV2Stub.newStub(factory, channel);
+  }
+
+  /**
+   * Creates a new blocking-style stub that supports unary and streaming output calls on the service
+   */
+  public static MxAccessGatewayBlockingStub newBlockingStub(
+      io.grpc.Channel channel) {
+    io.grpc.stub.AbstractStub.StubFactory<MxAccessGatewayBlockingStub> factory =
+      new io.grpc.stub.AbstractStub.StubFactory<MxAccessGatewayBlockingStub>() {
+        @java.lang.Override
+        public MxAccessGatewayBlockingStub newStub(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+          return new MxAccessGatewayBlockingStub(channel, callOptions);
+        }
+      };
+    return MxAccessGatewayBlockingStub.newStub(factory, channel);
+  }
+
+  /**
+   * Creates a new ListenableFuture-style stub that supports unary calls on the service
+   */
+  public static MxAccessGatewayFutureStub newFutureStub(
+      io.grpc.Channel channel) {
+    io.grpc.stub.AbstractStub.StubFactory<MxAccessGatewayFutureStub> factory =
+      new io.grpc.stub.AbstractStub.StubFactory<MxAccessGatewayFutureStub>() {
+        @java.lang.Override
+        public MxAccessGatewayFutureStub newStub(io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+          return new MxAccessGatewayFutureStub(channel, callOptions);
+        }
+      };
+    return MxAccessGatewayFutureStub.newStub(factory, channel);
+  }
+
+  /**
+   * <pre>
+   * Public client API for MXAccess sessions hosted by the gateway.
+   * </pre>
+   */
+  public interface AsyncService {
+
+    /**
+     */
+    default void openSession(mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getOpenSessionMethod(), responseObserver);
+    }
+
+    /**
+     */
+    default void closeSession(mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getCloseSessionMethod(), responseObserver);
+    }
+
+    /**
+     */
+    default void invoke(mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.MxCommandReply> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getInvokeMethod(), responseObserver);
+    }
+
+    /**
+     */
+    default void streamEvents(mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.MxEvent> responseObserver) {
+      io.grpc.stub.ServerCalls.asyncUnimplementedUnaryCall(getStreamEventsMethod(), responseObserver);
+    }
+  }
+
+  /**
+   * Base class for the server implementation of the service MxAccessGateway.
+   * <pre>
+   * Public client API for MXAccess sessions hosted by the gateway.
+   * </pre>
+   */
+  public static abstract class MxAccessGatewayImplBase
+      implements io.grpc.BindableService, AsyncService {
+
+    @java.lang.Override public final io.grpc.ServerServiceDefinition bindService() {
+      return MxAccessGatewayGrpc.bindService(this);
+    }
+  }
+
+  /**
+   * A stub to allow clients to do asynchronous rpc calls to service MxAccessGateway.
+   * <pre>
+   * Public client API for MXAccess sessions hosted by the gateway.
+   * </pre>
+   */
+  public static final class MxAccessGatewayStub
+      extends io.grpc.stub.AbstractAsyncStub<MxAccessGatewayStub> {
+    private MxAccessGatewayStub(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      super(channel, callOptions);
+    }
+
+    @java.lang.Override
+    protected MxAccessGatewayStub build(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      return new MxAccessGatewayStub(channel, callOptions);
+    }
+
+    /**
+     */
+    public void openSession(mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncUnaryCall(
+          getChannel().newCall(getOpenSessionMethod(), getCallOptions()), request, responseObserver);
+    }
+
+    /**
+     */
+    public void closeSession(mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncUnaryCall(
+          getChannel().newCall(getCloseSessionMethod(), getCallOptions()), request, responseObserver);
+    }
+
+    /**
+     */
+    public void invoke(mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.MxCommandReply> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncUnaryCall(
+          getChannel().newCall(getInvokeMethod(), getCallOptions()), request, responseObserver);
+    }
+
+    /**
+     */
+    public void streamEvents(mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest request,
+        io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.MxEvent> responseObserver) {
+      io.grpc.stub.ClientCalls.asyncServerStreamingCall(
+          getChannel().newCall(getStreamEventsMethod(), getCallOptions()), request, responseObserver);
+    }
+  }
+
+  /**
+   * A stub to allow clients to do synchronous rpc calls to service MxAccessGateway.
+   * <pre>
+   * Public client API for MXAccess sessions hosted by the gateway.
+   * </pre>
+   */
+  public static final class MxAccessGatewayBlockingV2Stub
+      extends io.grpc.stub.AbstractBlockingStub<MxAccessGatewayBlockingV2Stub> {
+    private MxAccessGatewayBlockingV2Stub(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      super(channel, callOptions);
+    }
+
+    @java.lang.Override
+    protected MxAccessGatewayBlockingV2Stub build(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      return new MxAccessGatewayBlockingV2Stub(channel, callOptions);
+    }
+
+    /**
+     */
+    public mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply openSession(mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest request) throws io.grpc.StatusException {
+      return io.grpc.stub.ClientCalls.blockingV2UnaryCall(
+          getChannel(), getOpenSessionMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply closeSession(mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest request) throws io.grpc.StatusException {
+      return io.grpc.stub.ClientCalls.blockingV2UnaryCall(
+          getChannel(), getCloseSessionMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public mxaccess_gateway.v1.MxaccessGateway.MxCommandReply invoke(mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest request) throws io.grpc.StatusException {
+      return io.grpc.stub.ClientCalls.blockingV2UnaryCall(
+          getChannel(), getInvokeMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    @io.grpc.ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
+    public io.grpc.stub.BlockingClientCall<?, mxaccess_gateway.v1.MxaccessGateway.MxEvent>
+        streamEvents(mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest request) {
+      return io.grpc.stub.ClientCalls.blockingV2ServerStreamingCall(
+          getChannel(), getStreamEventsMethod(), getCallOptions(), request);
+    }
+  }
+
+  /**
+   * A stub to allow clients to do limited synchronous rpc calls to service MxAccessGateway.
+   * <pre>
+   * Public client API for MXAccess sessions hosted by the gateway.
+   * </pre>
+   */
+  public static final class MxAccessGatewayBlockingStub
+      extends io.grpc.stub.AbstractBlockingStub<MxAccessGatewayBlockingStub> {
+    private MxAccessGatewayBlockingStub(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      super(channel, callOptions);
+    }
+
+    @java.lang.Override
+    protected MxAccessGatewayBlockingStub build(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      return new MxAccessGatewayBlockingStub(channel, callOptions);
+    }
+
+    /**
+     */
+    public mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply openSession(mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest request) {
+      return io.grpc.stub.ClientCalls.blockingUnaryCall(
+          getChannel(), getOpenSessionMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply closeSession(mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest request) {
+      return io.grpc.stub.ClientCalls.blockingUnaryCall(
+          getChannel(), getCloseSessionMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public mxaccess_gateway.v1.MxaccessGateway.MxCommandReply invoke(mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest request) {
+      return io.grpc.stub.ClientCalls.blockingUnaryCall(
+          getChannel(), getInvokeMethod(), getCallOptions(), request);
+    }
+
+    /**
+     */
+    public java.util.Iterator<mxaccess_gateway.v1.MxaccessGateway.MxEvent> streamEvents(
+        mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest request) {
+      return io.grpc.stub.ClientCalls.blockingServerStreamingCall(
+          getChannel(), getStreamEventsMethod(), getCallOptions(), request);
+    }
+  }
+
+  /**
+   * A stub to allow clients to do ListenableFuture-style rpc calls to service MxAccessGateway.
+   * <pre>
+   * Public client API for MXAccess sessions hosted by the gateway.
+   * </pre>
+   */
+  public static final class MxAccessGatewayFutureStub
+      extends io.grpc.stub.AbstractFutureStub<MxAccessGatewayFutureStub> {
+    private MxAccessGatewayFutureStub(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      super(channel, callOptions);
+    }
+
+    @java.lang.Override
+    protected MxAccessGatewayFutureStub build(
+        io.grpc.Channel channel, io.grpc.CallOptions callOptions) {
+      return new MxAccessGatewayFutureStub(channel, callOptions);
+    }
+
+    /**
+     */
+    public com.google.common.util.concurrent.ListenableFuture<mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply> openSession(
+        mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest request) {
+      return io.grpc.stub.ClientCalls.futureUnaryCall(
+          getChannel().newCall(getOpenSessionMethod(), getCallOptions()), request);
+    }
+
+    /**
+     */
+    public com.google.common.util.concurrent.ListenableFuture<mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply> closeSession(
+        mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest request) {
+      return io.grpc.stub.ClientCalls.futureUnaryCall(
+          getChannel().newCall(getCloseSessionMethod(), getCallOptions()), request);
+    }
+
+    /**
+     */
+    public com.google.common.util.concurrent.ListenableFuture<mxaccess_gateway.v1.MxaccessGateway.MxCommandReply> invoke(
+        mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest request) {
+      return io.grpc.stub.ClientCalls.futureUnaryCall(
+          getChannel().newCall(getInvokeMethod(), getCallOptions()), request);
+    }
+  }
+
+  private static final int METHODID_OPEN_SESSION = 0;
+  private static final int METHODID_CLOSE_SESSION = 1;
+  private static final int METHODID_INVOKE = 2;
+  private static final int METHODID_STREAM_EVENTS = 3;
+
+  private static final class MethodHandlers<Req, Resp> implements
+      io.grpc.stub.ServerCalls.UnaryMethod<Req, Resp>,
+      io.grpc.stub.ServerCalls.ServerStreamingMethod<Req, Resp>,
+      io.grpc.stub.ServerCalls.ClientStreamingMethod<Req, Resp>,
+      io.grpc.stub.ServerCalls.BidiStreamingMethod<Req, Resp> {
+    private final AsyncService serviceImpl;
+    private final int methodId;
+
+    MethodHandlers(AsyncService serviceImpl, int methodId) {
+      this.serviceImpl = serviceImpl;
+      this.methodId = methodId;
+    }
+
+    @java.lang.Override
+    @java.lang.SuppressWarnings("unchecked")
+    public void invoke(Req request, io.grpc.stub.StreamObserver<Resp> responseObserver) {
+      switch (methodId) {
+        case METHODID_OPEN_SESSION:
+          serviceImpl.openSession((mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest) request,
+              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply>) responseObserver);
+          break;
+        case METHODID_CLOSE_SESSION:
+          serviceImpl.closeSession((mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest) request,
+              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply>) responseObserver);
+          break;
+        case METHODID_INVOKE:
+          serviceImpl.invoke((mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest) request,
+              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.MxCommandReply>) responseObserver);
+          break;
+        case METHODID_STREAM_EVENTS:
+          serviceImpl.streamEvents((mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest) request,
+              (io.grpc.stub.StreamObserver<mxaccess_gateway.v1.MxaccessGateway.MxEvent>) responseObserver);
+          break;
+        default:
+          throw new AssertionError();
+      }
+    }
+
+    @java.lang.Override
+    @java.lang.SuppressWarnings("unchecked")
+    public io.grpc.stub.StreamObserver<Req> invoke(
+        io.grpc.stub.StreamObserver<Resp> responseObserver) {
+      switch (methodId) {
+        default:
+          throw new AssertionError();
+      }
+    }
+  }
+
+  public static final io.grpc.ServerServiceDefinition bindService(AsyncService service) {
+    return io.grpc.ServerServiceDefinition.builder(getServiceDescriptor())
+        .addMethod(
+          getOpenSessionMethod(),
+          io.grpc.stub.ServerCalls.asyncUnaryCall(
+            new MethodHandlers<
+              mxaccess_gateway.v1.MxaccessGateway.OpenSessionRequest,
+              mxaccess_gateway.v1.MxaccessGateway.OpenSessionReply>(
+                service, METHODID_OPEN_SESSION)))
+        .addMethod(
+          getCloseSessionMethod(),
+          io.grpc.stub.ServerCalls.asyncUnaryCall(
+            new MethodHandlers<
+              mxaccess_gateway.v1.MxaccessGateway.CloseSessionRequest,
+              mxaccess_gateway.v1.MxaccessGateway.CloseSessionReply>(
+                service, METHODID_CLOSE_SESSION)))
+        .addMethod(
+          getInvokeMethod(),
+          io.grpc.stub.ServerCalls.asyncUnaryCall(
+            new MethodHandlers<
+              mxaccess_gateway.v1.MxaccessGateway.MxCommandRequest,
+              mxaccess_gateway.v1.MxaccessGateway.MxCommandReply>(
+                service, METHODID_INVOKE)))
+        .addMethod(
+          getStreamEventsMethod(),
+          io.grpc.stub.ServerCalls.asyncServerStreamingCall(
+            new MethodHandlers<
+              mxaccess_gateway.v1.MxaccessGateway.StreamEventsRequest,
+              mxaccess_gateway.v1.MxaccessGateway.MxEvent>(
+                service, METHODID_STREAM_EVENTS)))
+        .build();
+  }
+
+  private static abstract class MxAccessGatewayBaseDescriptorSupplier
+      implements io.grpc.protobuf.ProtoFileDescriptorSupplier, io.grpc.protobuf.ProtoServiceDescriptorSupplier {
+    MxAccessGatewayBaseDescriptorSupplier() {}
+
+    @java.lang.Override
+    public com.google.protobuf.Descriptors.FileDescriptor getFileDescriptor() {
+      return mxaccess_gateway.v1.MxaccessGateway.getDescriptor();
+    }
+
+    @java.lang.Override
+    public com.google.protobuf.Descriptors.ServiceDescriptor getServiceDescriptor() {
+      return getFileDescriptor().findServiceByName("MxAccessGateway");
+    }
+  }
+
+  private static final class MxAccessGatewayFileDescriptorSupplier
+      extends MxAccessGatewayBaseDescriptorSupplier {
+    MxAccessGatewayFileDescriptorSupplier() {}
+  }
+
+  private static final class MxAccessGatewayMethodDescriptorSupplier
+      extends MxAccessGatewayBaseDescriptorSupplier
+      implements io.grpc.protobuf.ProtoMethodDescriptorSupplier {
+    private final java.lang.String methodName;
+
+    MxAccessGatewayMethodDescriptorSupplier(java.lang.String methodName) {
+      this.methodName = methodName;
+    }
+
+    @java.lang.Override
+    public com.google.protobuf.Descriptors.MethodDescriptor getMethodDescriptor() {
+      return getServiceDescriptor().findMethodByName(methodName);
+    }
+  }
+
+  private static volatile io.grpc.ServiceDescriptor serviceDescriptor;
+
+  public static io.grpc.ServiceDescriptor getServiceDescriptor() {
+    io.grpc.ServiceDescriptor result = serviceDescriptor;
+    if (result == null) {
+      synchronized (MxAccessGatewayGrpc.class) {
+        result = serviceDescriptor;
+        if (result == null) {
+          serviceDescriptor = result = io.grpc.ServiceDescriptor.newBuilder(SERVICE_NAME)
+              .setSchemaDescriptor(new MxAccessGatewayFileDescriptorSupplier())
+              .addMethod(getOpenSessionMethod())
+              .addMethod(getCloseSessionMethod())
+              .addMethod(getInvokeMethod())
+              .addMethod(getStreamEventsMethod())
+              .build();
+        }
+      }
+    }
+    return result;
+  }
+}

docs/client-proto-generation.md

@@ -137,9 +137,17 @@ The Python scaffold provides a repo-local generation script:
 clients/python/generate-proto.ps1
 ```
 
-Java clients should use the Gradle protobuf plugin and write generated sources
+Java clients use the Gradle protobuf plugin from `clients/java`. The
-under `clients/java/src/main/generated`. The Java client scaffold owns the
+`mxgateway-client` project reads the shared `.proto` files and writes generated
-Gradle plugin versions and source-set wiring.
+Java protobuf and gRPC sources under `clients/java/src/main/generated`, matching
+the manifest output path. Handwritten client and CLI code stays in the
+`mxgateway-client` and `mxgateway-cli` project source trees.
+
+Run the Java workspace checks from `clients/java`:
+
+```powershell
+gradle test
+```
 
 ## Golden Fixtures
 

docs/clients-java-design.md

@@ -17,6 +17,7 @@ Recommended Gradle multi-project layout:
 clients/java/
   settings.gradle
   build.gradle
+  src/main/generated/
   mxgateway-client/
     build.gradle
     src/main/java/com/dohertylan/mxgateway/client/
@@ -31,6 +32,7 @@ Alternative Maven layout is acceptable if the repo standardizes on Maven.
 Target Java:
 
 - Java 21 recommended.
+- The Gradle scaffold uses the Java 21 toolchain for compilation and tests.
 
 Expected dependencies:
 
@@ -189,3 +191,16 @@ Publish library and CLI separately:
 
 Generated protobuf code should be produced during the build from shared proto
 files and should not be hand-edited.
+
+## Current Build
+
+Run the Java scaffold checks from `clients/java`:
+
+```powershell
+gradle test
+```
+
+The `mxgateway-client` project generates the gateway and worker protobuf/gRPC
+bindings into `src/main/generated`, compiles the generated contracts, and runs
+JUnit 5 tests. The `mxgateway-cli` project builds a Picocli-based `mxgw-java`
+entry point for later command implementation.