The Java client workspace contains the MXAccess Gateway client library, generated protobuf/gRPC bindings, a Picocli test CLI project, and JUnit tests.

Layout

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-client exposes MxGatewayClientOptions, MxGatewayClient, MxGatewaySession, value/status helpers, typed gateway exceptions, raw generated stubs, and generated protobuf messages for parity tests.

mxgateway-cli depends on mxgateway-client and provides the mxgw-java application entry point. The CLI supports version, session, command, event streaming, write, and smoke-test commands with deterministic JSON output.

Regenerating Protobuf Bindings

Run generation from clients/java after the shared .proto files or Java output path changes:

gradle :mxgateway-client:generateProto

Client Usage

Create a client with explicit transport and auth options:

MxGatewayClientOptions options = MxGatewayClientOptions.builder()
        .endpoint("localhost:5000")
        .apiKey(System.getenv("MXGATEWAY_API_KEY"))
        .plaintext(true)
        .build();

try (MxGatewayClient client = MxGatewayClient.connect(options);
        MxGatewaySession session = client.openSession("java-client")) {
    int serverHandle = session.register("java-client");
    int itemHandle = session.addItem(serverHandle, "TestObject.TestInt");
    session.advise(serverHandle, itemHandle);
    session.write(serverHandle, itemHandle, MxValues.int32Value(123), 0);
}

Use rawBlockingStub, rawFutureStub, rawAsyncStub, openSessionRaw, closeSessionRaw, invoke, and raw session helper methods when tests need the underlying protobuf messages. MxGatewayCommandException and MxAccessException preserve the raw MxCommandReply when the gateway returns a data-bearing MXAccess failure.

MxEventStream implements Iterator<MxEvent> and AutoCloseable. Closing it cancels the underlying gRPC stream. Canceling or timing out a Java client call only stops the client from waiting; it does not abort an in-flight MXAccess COM call on the worker STA.

CLI Usage

Run the CLI through Gradle:

gradle :mxgateway-cli:run --args="version --json"
gradle :mxgateway-cli:run --args="open-session --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --client-session-name java-cli --json"
gradle :mxgateway-cli:run --args="register --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --client-name java-cli --json"
gradle :mxgateway-cli:run --args="add-item --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item TestObject.TestInt --json"
gradle :mxgateway-cli:run --args="advise --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --json"
gradle :mxgateway-cli:run --args="write --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --server-handle 1 --item-handle 1 --type int32 --value 123 --json"
gradle :mxgateway-cli:run --args="stream-events --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --session-id <id> --limit 1 --json"
gradle :mxgateway-cli:run --args="smoke --endpoint localhost:5000 --api-key-env MXGATEWAY_API_KEY --plaintext --item TestObject.TestInt --json"

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.

Use TLS options for a secured gateway:

gradle :mxgateway-cli:run --args="smoke --endpoint mxgateway.example.local:5001 --ca-file C:\certs\mxgateway-ca.pem --server-name-override mxgateway.example.local --api-key-env MXGATEWAY_API_KEY --item TestObject.TestInt --json"

Build And Test

Run the Java checks from clients/java:

gradle test

The build uses the Java 21 Gradle toolchain, compiles generated protobuf/gRPC code, and runs JUnit 5 tests for the client wrapper, shared behavior fixtures, in-process gRPC behavior, stream cancellation, and CLI parser/output behavior.

Packaging

Create local library and CLI artifacts from clients/java:

gradle :mxgateway-client:jar :mxgateway-cli:installDist

The library jar is under mxgateway-client/build/libs. The installed CLI distribution is under mxgateway-cli/build/install/mxgateway-cli.

Integration Checks

Run live checks only when a gateway and MXAccess-backed worker are available:

$env:MXGATEWAY_INTEGRATION = '1'
$env:MXGATEWAY_ENDPOINT = 'localhost:5000'
$env:MXGATEWAY_API_KEY = 'mxgw_key_id_secret'
$env:MXGATEWAY_TEST_ITEM = 'TestObject.TestInt'
gradle :mxgateway-cli:run --args="smoke --endpoint $env:MXGATEWAY_ENDPOINT --plaintext --api-key-env MXGATEWAY_API_KEY --item $env:MXGATEWAY_TEST_ITEM --json"

README.md

Java Client