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

Class MxGatewaySession

java.lang.Object
com.zb.mom.ww.mxgateway.client.MxGatewaySession
All Implemented Interfaces:
AutoCloseable
public final class MxGatewaySession extends Object implements AutoCloseable
Typed handle for a single MXAccess gateway session.

Wraps an MxaccessGateway.OpenSessionReply together with the MxGatewayClient that opened it and exposes the MXAccess command surface (Register, AddItem, Advise, bulk subscribe variants, Write, event streaming, and close). Each command request carries a freshly generated client correlation id.

  • Method Details

    • forSessionId

      public static MxGatewaySession forSessionId(MxGatewayClient client, String sessionId)
      Builds a session handle for an existing gateway session id without issuing an OpenSession call. Useful for CLI tools that operate against a session opened in a separate invocation.
      Parameters:
      client - the gateway client used for further commands
      sessionId - the existing gateway session id
      Returns:
      a session handle bound to the supplied id

    • sessionId

      public String sessionId()
      Returns the gateway-assigned session id.
      Returns:
      the session id

    • openReply

      public MxaccessGateway.OpenSessionReply openReply()
      Returns the original MxaccessGateway.OpenSessionReply that this session was opened with.
      Returns:
      the open-session reply

    • closeRaw

      public MxaccessGateway.CloseSessionReply closeRaw()
      Sends a CloseSession RPC and caches the reply so subsequent calls are idempotent.
      Returns:
      the raw close-session reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • close

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

    • register

      public int register(String clientName)
      Invokes MXAccess Register and returns the server handle.
      Parameters:
      clientName - the MXAccess client name to register
      Returns:
      the ServerHandle returned by MXAccess
      Throws:
      MxGatewayException - on transport or protocol failure

    • registerRaw

      public MxaccessGateway.MxCommandReply registerRaw(String clientName)
      Invokes MXAccess Register and returns the raw reply.
      Parameters:
      clientName - the MXAccess client name to register
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • unregister

      public void unregister(int serverHandle)
      Invokes MXAccess Unregister.
      Parameters:
      serverHandle - the ServerHandle returned by register(String)
      Throws:
      MxGatewayException - on transport or protocol failure

    • addItem

      public int addItem(int serverHandle, String itemDefinition)
      Invokes MXAccess AddItem and returns the new item handle.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemDefinition - the MXAccess item definition (tag reference)
      Returns:
      the ItemHandle assigned by MXAccess
      Throws:
      MxGatewayException - on transport or protocol failure

    • addItemRaw

      public MxaccessGateway.MxCommandReply addItemRaw(int serverHandle, String itemDefinition)
      Invokes MXAccess AddItem and returns the raw reply.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemDefinition - the MXAccess item definition
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • addItem2

      public int addItem2(int serverHandle, String itemDefinition, String itemContext)
      Invokes MXAccess AddItem2 and returns the new item handle.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemDefinition - the MXAccess item definition
      itemContext - the MXAccess item context (e.g. galaxy/object scope)
      Returns:
      the ItemHandle assigned by MXAccess
      Throws:
      MxGatewayException - on transport or protocol failure

    • addItem2Raw

      public MxaccessGateway.MxCommandReply addItem2Raw(int serverHandle, String itemDefinition, String itemContext)
      Invokes MXAccess AddItem2 and returns the raw reply.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemDefinition - the MXAccess item definition
      itemContext - the MXAccess item context
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • removeItem

      public void removeItem(int serverHandle, int itemHandle)
      Invokes MXAccess RemoveItem.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to remove
      Throws:
      MxGatewayException - on transport or protocol failure

    • removeItemRaw

      public MxaccessGateway.MxCommandReply removeItemRaw(int serverHandle, int itemHandle)
      Invokes MXAccess RemoveItem and returns the raw reply.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to remove
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • advise

      public void advise(int serverHandle, int itemHandle)
      Invokes MXAccess Advise so the item starts emitting data-change events.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to advise
      Throws:
      MxGatewayException - on transport or protocol failure

    • adviseRaw

      public MxaccessGateway.MxCommandReply adviseRaw(int serverHandle, int itemHandle)
      Invokes MXAccess Advise and returns the raw reply.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to advise
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • unAdvise

      public void unAdvise(int serverHandle, int itemHandle)
      Invokes MXAccess UnAdvise so the item stops emitting data-change events.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to un-advise
      Throws:
      MxGatewayException - on transport or protocol failure

    • unAdviseRaw

      public MxaccessGateway.MxCommandReply unAdviseRaw(int serverHandle, int itemHandle)
      Invokes MXAccess UnAdvise and returns the raw reply.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to un-advise
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • addItemBulk

      public List<MxaccessGateway.SubscribeResult> addItemBulk(int serverHandle, List<String> tagAddresses)
      Invokes the bulk AddItem variant.
      Parameters:
      serverHandle - the ServerHandle owning the items
      tagAddresses - the MXAccess tag addresses to add
      Returns:
      a per-tag MxaccessGateway.SubscribeResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if tagAddresses is null

    • adviseItemBulk

      public List<MxaccessGateway.SubscribeResult> adviseItemBulk(int serverHandle, List<Integer> itemHandles)
      Invokes the bulk Advise variant.
      Parameters:
      serverHandle - the ServerHandle owning the items
      itemHandles - the ItemHandle list to advise
      Returns:
      a per-item MxaccessGateway.SubscribeResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if itemHandles is null

    • removeItemBulk

      public List<MxaccessGateway.SubscribeResult> removeItemBulk(int serverHandle, List<Integer> itemHandles)
      Invokes the bulk RemoveItem variant.
      Parameters:
      serverHandle - the ServerHandle owning the items
      itemHandles - the ItemHandle list to remove
      Returns:
      a per-item MxaccessGateway.SubscribeResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if itemHandles is null

    • unAdviseItemBulk

      public List<MxaccessGateway.SubscribeResult> unAdviseItemBulk(int serverHandle, List<Integer> itemHandles)
      Invokes the bulk UnAdvise variant.
      Parameters:
      serverHandle - the ServerHandle owning the items
      itemHandles - the ItemHandle list to un-advise
      Returns:
      a per-item MxaccessGateway.SubscribeResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if itemHandles is null

    • subscribeBulk

      public List<MxaccessGateway.SubscribeResult> subscribeBulk(int serverHandle, List<String> tagAddresses)
      Invokes the gateway SubscribeBulk convenience that combines AddItem and Advise for the supplied tag addresses.
      Parameters:
      serverHandle - the ServerHandle owning the items
      tagAddresses - the MXAccess tag addresses to subscribe
      Returns:
      a per-tag MxaccessGateway.SubscribeResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if tagAddresses is null

    • unsubscribeBulk

      public List<MxaccessGateway.SubscribeResult> unsubscribeBulk(int serverHandle, List<Integer> itemHandles)
      Invokes the gateway UnsubscribeBulk convenience that combines UnAdvise and RemoveItem for the supplied item handles.
      Parameters:
      serverHandle - the ServerHandle owning the items
      itemHandles - the ItemHandle list to unsubscribe
      Returns:
      a per-item MxaccessGateway.SubscribeResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if itemHandles is null

    • writeBulk

      public List<MxaccessGateway.BulkWriteResult> writeBulk(int serverHandle, List<MxaccessGateway.WriteBulkEntry> entries)
      Bulk Write — sequential MXAccess Write per entry on the worker's STA.

      Per-entry failures appear as MxaccessGateway.BulkWriteResult entries with wasSuccessful == false; this method does not throw for per-entry MXAccess failures (it still throws MxGatewayException on transport or protocol-level failures).

      Parameters:
      serverHandle - the ServerHandle owning the items
      entries - the per-item (handle, value, user id) tuples
      Returns:
      a per-entry MxaccessGateway.BulkWriteResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if entries is null

    • write2Bulk

      public List<MxaccessGateway.BulkWriteResult> write2Bulk(int serverHandle, List<MxaccessGateway.Write2BulkEntry> entries)
      Bulk Write2 — sequential MXAccess Write2 (timestamped) per entry.

      Per-entry semantics mirror writeBulk(int, List).

      Parameters:
      serverHandle - the ServerHandle owning the items
      entries - the per-item (handle, value, timestamp, user id) tuples
      Returns:
      a per-entry MxaccessGateway.BulkWriteResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if entries is null

    • writeSecuredBulk

      public List<MxaccessGateway.BulkWriteResult> writeSecuredBulk(int serverHandle, List<MxaccessGateway.WriteSecuredBulkEntry> entries)
      Bulk WriteSecured — credential-sensitive values must not be logged by callers; mirrors the single-item write-secured redaction contract.

      Per-entry semantics mirror writeBulk(int, List).

      Parameters:
      serverHandle - the ServerHandle owning the items
      entries - the per-item (handle, value, current+verifier user id) tuples
      Returns:
      a per-entry MxaccessGateway.BulkWriteResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if entries is null

    • writeSecured2Bulk

      public List<MxaccessGateway.BulkWriteResult> writeSecured2Bulk(int serverHandle, List<MxaccessGateway.WriteSecured2BulkEntry> entries)
      Bulk WriteSecured2 — sequential timestamped + verified write per entry.

      Per-entry semantics mirror writeBulk(int, List).

      Parameters:
      serverHandle - the ServerHandle owning the items
      entries - the per-item (handle, value, timestamp, current+verifier user id) tuples
      Returns:
      a per-entry MxaccessGateway.BulkWriteResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if entries is null

    • readBulk

      public List<MxaccessGateway.BulkReadResult> readBulk(int serverHandle, List<String> tagAddresses, Duration timeout)
      Bulk Read — snapshot the current value of each requested tag.

      MXAccess COM has no synchronous read; the worker returns the cached OnDataChange value for any tag that is already advised (wasCached == true) without modifying the existing subscription, and falls back to a full AddItem + Advise + wait + UnAdvise + RemoveItem snapshot lifecycle otherwise. The supplied timeout bounds the per-tag wait in the snapshot case; pass Duration.ZERO (or null) to use the worker default (1000 ms). Per-tag failures appear as MxaccessGateway.BulkReadResult entries with wasSuccessful == false; this method does not throw for per-tag MXAccess failures.

      Parameters:
      serverHandle - the ServerHandle owning the items
      tagAddresses - the tag addresses to read
      timeout - per-tag snapshot timeout (zero or null = worker default)
      Returns:
      a per-tag MxaccessGateway.BulkReadResult list
      Throws:
      MxGatewayException - on transport or protocol failure
      NullPointerException - if tagAddresses is null
      IllegalArgumentException - if timeout is negative or exceeds Integer.MAX_VALUE milliseconds

    • write

      public void write(int serverHandle, int itemHandle, MxaccessGateway.MxValue value, int userId)
      Invokes MXAccess Write.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to write
      value - the value to write
      userId - the MXAccess user id used for security checks
      Throws:
      MxGatewayException - on transport or protocol failure

    • writeRaw

      public MxaccessGateway.MxCommandReply writeRaw(int serverHandle, int itemHandle, MxaccessGateway.MxValue value, int userId)
      Invokes MXAccess Write and returns the raw reply.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to write
      value - the value to write
      userId - the MXAccess user id used for security checks
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure

    • writeArrayElements

      public void writeArrayElements(int serverHandle, int itemHandle, MxaccessGateway.MxDataType elementDataType, int totalLength, Map<Integer,MxaccessGateway.MxValue> elements, int userId)
      Writes a subset of an array's elements using MXAccess Write, building a write-only MxaccessGateway.MxSparseArray value that the gateway expands into a full, default-filled array before forwarding to the worker.

      Default-fill semantics: only the indices supplied in elements are written; every unmentioned index is reset to the element type's default (for example 0, false, or an empty string), not preserved from the array's current contents. Use a full MxaccessGateway.MxValue array write when you need to keep existing element values.

      totalLength is required and defines the length of the expanded array; supplied indices must be within [0, totalLength). Elements are iterated in ascending index order so the produced command is deterministic.

      Because the proto fields MxSparseArray.total_length and MxSparseElement.index are uint32, passing a negative Java int would silently sign-extend to a large unsigned value on the wire. This method therefore rejects negative totalLength and negative element indices with IllegalArgumentException rather than allowing a hard-to-diagnose gateway error.

      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to write
      elementDataType - the MxaccessGateway.MxDataType of the array's elements
      totalLength - the total length of the expanded array; must be > 0
      elements - the indices to write mapped to their scalar values; each index must be in [0, totalLength); unmentioned indices are reset to the element type default
      userId - the MXAccess user id used for security checks
      Throws:
      IllegalArgumentException - if totalLength is not positive, or if any element index is negative or ≥ totalLength
      MxGatewayException - on transport or protocol failure

    • write2

      public void write2(int serverHandle, int itemHandle, MxaccessGateway.MxValue value, MxaccessGateway.MxValue timestampValue, int userId)
      Invokes MXAccess Write2, which carries an explicit timestamp.
      Parameters:
      serverHandle - the ServerHandle owning the item
      itemHandle - the ItemHandle to write
      value - the value to write
      timestampValue - the timestamp value to associate with the write
      userId - the MXAccess user id used for security checks
      Throws:
      MxGatewayException - on transport or protocol failure

    • streamEvents

      public MxEventStream streamEvents()
      Subscribes to gateway events for this session starting from the beginning of the worker event log.
      Returns:
      an iterator-style stream of events

    • streamEventsAfter

      public MxEventStream streamEventsAfter(long afterWorkerSequence)
      Subscribes to gateway events for this session starting after the supplied worker sequence number.
      Parameters:
      afterWorkerSequence - the resume cursor; events with worker sequence greater than this value are delivered
      Returns:
      an iterator-style stream of events

    • invokeCommand

      public MxaccessGateway.MxCommandReply invokeCommand(MxaccessGateway.MxCommand command)
      Sends a pre-built MxaccessGateway.MxCommand for this session and returns the raw reply, attaching a freshly generated client correlation id.
      Parameters:
      command - the command to send
      Returns:
      the raw command reply
      Throws:
      MxGatewayException - on transport or protocol failure