Package com.ultikits.ultitools.websocket

Interface CloudChannel

All Known Implementing Classes:
AgentProtocol.LiveChannel, FramedChannel
@Internal public interface CloudChannel
Frames and sends UltiCloud protocol v2 messages; internal, not for module use.

Sending methods return true only when the requested frame was handed to the socket, not when the gateway acknowledged it. False means the requested frame was not handed off: the channel may be closed, the socket may refuse it, or the frame may be too large. An oversized reply may instead send a correlated error payload_too_large and still return false. Payloads must already match their message schemas.

Since:
6.3.1

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    isOpen()
    Reports protocol readiness, not merely whether the socket is connected.
    CloudLimits
    limits()
    Returns the current connection's accepted limits, or defaults before welcome.
    boolean
    reply(String replyTo, String type, com.google.gson.JsonObject payload)
    Sends a correlated reply with a fresh id and timestamp.
    boolean
    replyError(String replyTo, String type, String code, String message, com.google.gson.JsonObject detailsOrNull)
    Replies with code, message and optional details.
    boolean
    replyOk(String replyTo, String type, com.google.gson.JsonElement data)
    Replies with an OpOutcome payload containing status: ok and data.
    default boolean
    replyOk(String replyTo, String type, com.google.gson.JsonElement data, String messageOrNull)
    Replies with an OpOutcome payload containing status: ok, data and an optional message, for result types whose ok variant declares one.
    boolean
    replyPartial(String replyTo, String type, com.google.gson.JsonElement data, String codeOrNull, String messageOrNull)
    Replies with status: partial; only result types declaring partial allow this.
    boolean
    send(String type, com.google.gson.JsonObject payload)
    Sends a message with a fresh id and timestamp, without a replyTo field.
    default String
    sendTracked(String type, com.google.gson.JsonObject payload)
    Sends a message with a fresh id and timestamp, without a replyTo field, and reports the envelope id it used so the caller can correlate a later reply to this frame.
    default String
    sendTracked(String type, com.google.gson.JsonObject payload, Consumer<String> beforeHandOff)
    Sends like sendTracked(String, JsonObject), but hands the envelope id to beforeHandOff before the frame reaches the socket.

  • Method Details

    • isOpen

      boolean isOpen()
      Reports protocol readiness, not merely whether the socket is connected.
      Returns:
      true only after an accepted welcome and before the connection closes

    • limits

      CloudLimits limits()
      Returns the current connection's accepted limits, or defaults before welcome.
      Returns:
      the immutable limits snapshot

    • send

      boolean send(String type, com.google.gson.JsonObject payload)
      Sends a message with a fresh id and timestamp, without a replyTo field.
      Parameters:
      type - a registered message type that does not require replyTo
      payload - the schema-valid message payload
      Returns:
      true if the requested frame was handed to the socket
      Throws:
      IllegalArgumentException - if the type is unknown or requires replyTo

    • sendTracked

      default String sendTracked(String type, com.google.gson.JsonObject payload)
      Sends a message with a fresh id and timestamp, without a replyTo field, and reports the envelope id it used so the caller can correlate a later reply to this frame.

      The default implementation cannot report the id and refuses; channels used by the framework implement it so the id and the send path cannot diverge from send(java.lang.String, com.google.gson.JsonObject).

      Parameters:
      type - a registered message type that does not require replyTo
      payload - the schema-valid message payload
      Returns:
      the envelope id of the frame handed to the socket, or null when nothing was handed off, including a closed channel or an oversized frame
      Throws:
      IllegalArgumentException - if the type is unknown or requires replyTo
      UnsupportedOperationException - if the channel cannot report the id it used
      Since:
      6.3.1

    • sendTracked

      default String sendTracked(String type, com.google.gson.JsonObject payload, Consumer<String> beforeHandOff)
      Sends like sendTracked(String, JsonObject), but hands the envelope id to beforeHandOff before the frame reaches the socket. A caller that correlates the reply registers its pending entry there, so a reply processed on another thread can never arrive before the entry exists. When the result is null the frame was not handed off and the caller rolls its registration back; the hook may then have run or not.
      Parameters:
      type - a registered message type that does not require replyTo
      payload - the schema-valid message payload
      beforeHandOff - receives the envelope id before the hand-off; must not block or throw
      Returns:
      the envelope id of the frame handed to the socket, or null when nothing was handed off
      Throws:
      IllegalArgumentException - if the type is unknown or requires replyTo
      UnsupportedOperationException - if the channel cannot report the id it used
      Since:
      6.3.1

    • reply

      boolean reply(String replyTo, String type, com.google.gson.JsonObject payload)
      Sends a correlated reply with a fresh id and timestamp.
      Parameters:
      replyTo - the request's ULID, never null
      type - a registered message type that allows replyTo
      payload - the schema-valid reply payload
      Returns:
      true if the requested reply was handed to the socket
      Throws:
      IllegalArgumentException - if the type or correlation id is invalid

    • replyOk

      boolean replyOk(String replyTo, String type, com.google.gson.JsonElement data)
      Replies with an OpOutcome payload containing status: ok and data.
      Parameters:
      replyTo - the request's ULID
      type - the result message type
      data - result data matching that type's schema, including JSON null where allowed
      Returns:
      true if the requested reply was handed to the socket

    • replyOk

      default boolean replyOk(String replyTo, String type, com.google.gson.JsonElement data, String messageOrNull)
      Replies with an OpOutcome payload containing status: ok, data and an optional message, for result types whose ok variant declares one.

      A channel that cannot carry the message refuses instead of silently dropping it, so a caller never believes an explanation reached the panel when it did not.

      Parameters:
      replyTo - the request's ULID
      type - the result message type
      data - result data matching that type's schema, including JSON null where allowed
      messageOrNull - a safe result message (1..500 characters), or null to omit it
      Returns:
      true if the requested reply was handed to the socket
      Throws:
      UnsupportedOperationException - if the channel cannot send an ok message
      Since:
      6.3.1

    • replyPartial

      boolean replyPartial(String replyTo, String type, com.google.gson.JsonElement data, String codeOrNull, String messageOrNull)
      Replies with status: partial; only result types declaring partial allow this.
      Parameters:
      replyTo - the request's ULID
      type - the result message type
      data - partial result data matching that type's schema
      codeOrNull - an allowed result code, or null to omit it
      messageOrNull - a safe result message, or null to omit it
      Returns:
      true if the requested reply was handed to the socket

    • replyError

      boolean replyError(String replyTo, String type, String code, String message, com.google.gson.JsonObject detailsOrNull)
      Replies with code, message and optional details. Result types include status: error; the generic error type omits status.
      Parameters:
      replyTo - the request's ULID
      type - the result message type or error
      code - an error code allowed for that type
      message - a safe diagnostic, never a credential or raw exception message
      detailsOrNull - schema-valid details, or null to omit them
      Returns:
      true if the requested reply was handed to the socket