Package com.zb.mom.ww.mxgateway.client

Class MxGatewayClient

java.lang.Object
com.zb.mom.ww.mxgateway.client.MxGatewayClient
All Implemented Interfaces:
AutoCloseable
public final class MxGatewayClient extends Object implements AutoCloseable
Idiomatic Java wrapper around the generated MxAccessGateway gRPC stubs.

Owns or borrows a ManagedChannel, attaches a MxGatewayAuthInterceptor carrying the configured API key, and exposes blocking, future, and async stub variants. Translates protocol status failures into typed MxGatewayException subclasses.

  • Constructor Details

    • MxGatewayClient

      public MxGatewayClient(io.grpc.Channel channel, MxGatewayClientOptions options)
      Constructs a client over a caller-managed Channel. The caller owns channel lifecycle; close() is a no-op for this constructor.
      Parameters:
      channel - the gRPC channel to use for outbound calls
      options - the client options carrying the API key and timeouts
      Throws:
      NullPointerException - if options is null

  • Method Details

    • connect

      public static MxGatewayClient connect(MxGatewayClientOptions options)
      Builds a new client and owns its channel; close() shuts the channel down.
      Parameters:
      options - the client options carrying the endpoint and credentials
      Returns:
      a connected client

    • rawBlockingStub

      public MxAccessGatewayGrpc.MxAccessGatewayBlockingStub rawBlockingStub()
      Returns the underlying blocking stub with the per-call deadline applied.
      Returns:
      the blocking stub

    • rawFutureStub

      public MxAccessGatewayGrpc.MxAccessGatewayFutureStub rawFutureStub()
      Returns the underlying future stub with the per-call deadline applied.
      Returns:
      the future stub

    • rawAsyncStub

      public MxAccessGatewayGrpc.MxAccessGatewayStub rawAsyncStub()
      Returns the underlying async stub. Stream deadlines are applied per call.
      Returns:
      the async stub

    • openSession

      public MxGatewaySession openSession(MxaccessGateway.OpenSessionRequest request)
      Opens a gateway session and returns a typed handle for further commands.
      Parameters:
      request - the OpenSessionRequest to send
      Returns:
      a session bound to the resulting OpenSessionReply
      Throws:
      MxGatewayException - on transport or protocol failure

    • openSession

      public MxGatewaySession openSession(String clientSessionName)
      Opens a gateway session using the configured call timeout for the worker command timeout and a caller-supplied client session name.
      Parameters:
      clientSessionName - the human-readable session name reported by the gateway
      Returns:
      a session bound to the resulting OpenSessionReply
      Throws:
      MxGatewayException - on transport or protocol failure

    • openSessionRaw

      public MxaccessGateway.OpenSessionReply openSessionRaw(MxaccessGateway.OpenSessionRequest request)
      Invokes OpenSession and returns the raw reply.
      Parameters:
      request - the OpenSessionRequest to send
      Returns:
      the raw OpenSessionReply
      Throws:
      MxGatewayException - on transport or protocol failure

    • openSessionAsync

      public CompletableFuture<MxaccessGateway.OpenSessionReply> openSessionAsync(MxaccessGateway.OpenSessionRequest request)
      Invokes OpenSession asynchronously.
      Parameters:
      request - the OpenSessionRequest to send
      Returns:
      a future completed with the raw reply, or completed exceptionally with MxGatewayException on failure

    • invoke

      public MxaccessGateway.MxCommandReply invoke(MxaccessGateway.MxCommandRequest request)
      Invokes the Invoke unary RPC and validates both the protocol status and any MXAccess-side failure carried in the reply.
      Parameters:
      request - the MxCommandRequest to send
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure
      MxAccessException - when the worker reports an MXAccess COM-side failure

    • invokeAsync

      public CompletableFuture<MxaccessGateway.MxCommandReply> invokeAsync(MxaccessGateway.MxCommandRequest request)
      Invokes the Invoke RPC asynchronously.
      Parameters:
      request - the MxCommandRequest to send
      Returns:
      a future completed with the raw reply, or completed exceptionally with MxGatewayException (including MxAccessException) on failure

    • closeSessionRaw

      public MxaccessGateway.CloseSessionReply closeSessionRaw(MxaccessGateway.CloseSessionRequest request)
      Invokes the CloseSession unary RPC.
      Parameters:
      request - the CloseSessionRequest to send
      Returns:
      the raw reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • streamEvents

      public MxEventStream streamEvents(MxaccessGateway.StreamEventsRequest request)
      Subscribes to the StreamEvents server-streaming RPC and exposes results as a blocking iterator. Closing the returned stream cancels the underlying gRPC call.
      Parameters:
      request - the StreamEventsRequest carrying the session id and resume cursor
      Returns:
      an iterator-style stream of events

    • streamEventsAsync

      public MxGatewayEventSubscription streamEventsAsync(MxaccessGateway.StreamEventsRequest request, io.grpc.stub.StreamObserver<MxaccessGateway.MxEvent> observer)
      Subscribes to StreamEvents and dispatches each event to the supplied observer. The returned subscription is cancellable.
      Parameters:
      request - the StreamEventsRequest to send
      observer - caller-supplied observer that receives events and completion
      Returns:
      a cancellable subscription handle

    • acknowledgeAlarm

      public MxaccessGateway.AcknowledgeAlarmReply acknowledgeAlarm(MxaccessGateway.AcknowledgeAlarmRequest request)
      Acknowledges an active MXAccess alarm condition through the gateway.

      The gateway authenticates the request against the API key's invoke:alarm-ack scope and forwards the acknowledge to the worker's MXAccess session; the resulting native MxStatus is returned in the reply. Acks are idempotent at the MxAccess layer.

      Parameters:
      request - the AcknowledgeAlarmRequest
      Returns:
      the raw acknowledge reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • acknowledgeAlarmAsync

      public CompletableFuture<MxaccessGateway.AcknowledgeAlarmReply> acknowledgeAlarmAsync(MxaccessGateway.AcknowledgeAlarmRequest request)
      Acknowledges an active MXAccess alarm condition asynchronously.
      Parameters:
      request - the AcknowledgeAlarmRequest
      Returns:
      a future completed with the raw reply, or completed exceptionally with MxGatewayException on failure

    • queryActiveAlarms

      public MxGatewayActiveAlarmsSubscription queryActiveAlarms(MxaccessGateway.QueryActiveAlarmsRequest request, io.grpc.stub.StreamObserver<MxaccessGateway.ActiveAlarmSnapshot> observer)
      Streams a snapshot of all alarms currently Active or ActiveAcked — the gateway's ConditionRefresh equivalent. Used after reconnect to seed local Part 9 state.
      Parameters:
      request - the QueryActiveAlarmsRequest, optionally scoped by alarm-reference prefix
      observer - caller-supplied observer that receives snapshots and completion
      Returns:
      a cancellable subscription handle

    • streamAlarms

      public MxGatewayAlarmFeedSubscription streamAlarms(MxaccessGateway.StreamAlarmsRequest request, io.grpc.stub.StreamObserver<MxaccessGateway.AlarmFeedMessage> observer)
      Attaches to the gateway's central alarm feed. The stream opens with one AlarmFeedMessage per currently-active alarm (the ConditionRefresh snapshot), then a single snapshot_complete, then a transition for every subsequent raise / acknowledge / clear.

      Served by the gateway's always-on alarm monitor — no worker session is opened — so any number of clients may attach.

      Parameters:
      request - the StreamAlarmsRequest, optionally scoped by alarm-reference prefix
      observer - caller-supplied observer that receives feed messages and completion
      Returns:
      a cancellable subscription handle

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • closeAndAwaitTermination

      public void closeAndAwaitTermination() throws InterruptedException
      Shuts the owned channel down and waits up to the configured connect timeout for termination, forcibly shutting it down on timeout. No-op for clients that do not own their channel.
      Throws:
      InterruptedException - if the calling thread is interrupted while waiting