Package io.fluxcapacitor.javaclient.web

Interface SocketSession

All Known Implementing Classes:
DefaultSocketSession
public interface SocketSession
Represents a WebSocket session that allows sending messages, requests, pings, and handling session lifecycle actions. This interface provides both default and customizable behaviors for interacting with a WebSocket session.

  • Method Summary

    Modifier and Type
    Method
    Description
    default void
    close()
    Closes the WebSocket session using the default closing behavior.
    default void
    close(int closeReason)
    Closes the WebSocket session using the specified close reason and a default guarantee of Guarantee.NONE.
    CompletableFuture<Void>
    close(int closeReason, Guarantee guarantee)
    Closes the WebSocket session with the specified close reason and delivery guarantee.
    default CompletableFuture<Void>
    close(Guarantee guarantee)
    Closes the WebSocket session with the specified guarantee for handling pending operations.
    boolean
    isOpen()
    Determines whether the WebSocket session is currently open.
    default void
    sendMessage(Object value)
    Sends a message over the WebSocket session with the specified value, using the Guarantee.NONE policy.
    CompletableFuture<Void>
    sendMessage(Object value, Guarantee guarantee)
    Sends a message over the WebSocket session with the specified delivery guarantee.
    default void
    sendPing(Object value)
    Sends a WebSocket ping message with the given value.
    CompletableFuture<Void>
    sendPing(Object value, Guarantee guarantee)
    Sends a ping message with the specified value to the WebSocket session.
    default <R> CompletionStage<R>
    sendRequest(Request<R> request)
    Sends a request and returns a CompletionStage representing the pending result.
    <R> CompletionStage<R>
    sendRequest(Request<R> request, Duration timeout)
    Sends a request over the WebSocket session with a specified timeout duration.
    String
    sessionId()
    Retrieves the unique identifier for the current WebSocket session.

  • Method Details

    • sessionId

      String sessionId()
      Retrieves the unique identifier for the current WebSocket session.
      Returns:
      a string representing the unique session ID for the WebSocket session.

    • sendMessage

      default void sendMessage(Object value)
      Sends a message over the WebSocket session with the specified value, using the Guarantee.NONE policy.
      Parameters:
      value - the value of the message to be sent. The value will be serialized and transmitted as bytes.

    • sendMessage

      CompletableFuture<Void> sendMessage(Object value, Guarantee guarantee)
      Sends a message over the WebSocket session with the specified delivery guarantee.
      Parameters:
      value - the value of the message to be sent. The value will be serialized and transmitted as bytes.
      guarantee - the delivery guarantee for the message.
      Returns:
      a CompletableFuture that completes when the message has been sent or stored, or fails with an exception if that operation fails.

    • sendRequest

      default <R> CompletionStage<R> sendRequest(Request<R> request)
      Sends a request and returns a CompletionStage representing the pending result. This method asynchronously sends * the given request and waits for the corresponding response. The request object will be wrapped by SocketRequest and then sent over the WebSocket session. Once the session receives a SocketResponse the request will be completed.

      The timeout for the request is determined based on the Timeout annotation on the request class. If no Timeout annotation is present, a default timeout of 30 seconds is applied.

      Type Parameters:
      R - the type of the expected response from the request
      Parameters:
      request - the request to be sent, encapsulating the type of response expected
      Returns:
      a CompletionStage representing the asynchronous result of the request
      See Also:

    • sendRequest

      <R> CompletionStage<R> sendRequest(Request<R> request, Duration timeout)
      Sends a request over the WebSocket session with a specified timeout duration. This method asynchronously sends the given request and waits for the corresponding response. The request object will be wrapped by SocketRequest and then sent over the WebSocket session. Once the session receives a SocketResponse the request will be completed.
      Type Parameters:
      R - the type of the response expected from the request
      Parameters:
      request - the request object to be sent
      timeout - the timeout duration for the request, after which it will fail if no response is received
      Returns:
      a CompletionStage<R> that completes with the response of the specified type R or completes exceptionally if an error occurs or the timeout is exceeded
      See Also:

    • sendPing

      default void sendPing(Object value)
      Sends a WebSocket ping message with the given value. The ping will be sent without any specific delivery guarantees.
      Parameters:
      value - the object to be sent as a ping message, which will be serialized and transmitted over the WebSocket

    • sendPing

      CompletableFuture<Void> sendPing(Object value, Guarantee guarantee)
      Sends a ping message with the specified value to the WebSocket session.
      Parameters:
      value - the value to be included in the ping message. This can be any object that is serializable or manageable according to the WebSocket session's implementation.
      guarantee - the delivery guarantee for the ping message. It specifies how assurances (e.g., sending, storing) are handled for the message delivery.
      Returns:
      a CompletableFuture that completes once the ping message is processed or the delivery guarantee has been fulfilled.

    • close

      default void close()
      Closes the WebSocket session using the default closing behavior. This method triggers the close operation with a close reason code of 1000 (normal closure) and a Guarantee of NONE.

    • close

      default void close(int closeReason)
      Closes the WebSocket session using the specified close reason and a default guarantee of Guarantee.NONE.
      Parameters:
      closeReason - the reason for closing the session, represented as an integer. Standard WebSocket close codes can be used (e.g., 1000 for normal closure).

    • close

      default CompletableFuture<Void> close(Guarantee guarantee)
      Closes the WebSocket session with the specified guarantee for handling pending operations.
      Parameters:
      guarantee - the level of guarantee to be applied for handling pending messages or pings before closing the session. This can be NONE, SENT, or STORED.
      Returns:
      a CompletableFuture that completes when the closing operation is finished.

    • close

      CompletableFuture<Void> close(int closeReason, Guarantee guarantee)
      Closes the WebSocket session with the specified close reason and delivery guarantee.
      Parameters:
      closeReason - an integer indicating the reason for closing the WebSocket session, typically based on WebSocket close codes (e.g., 1000 for normal closure).
      guarantee - the delivery guarantee for ensuring the closure message is sent, which can be one of the Guarantee values: NONE, SENT, or STORED.
      Returns:
      a CompletableFuture<Void> that completes when the close operation is performed successfully.

    • isOpen

      boolean isOpen()
      Determines whether the WebSocket session is currently open.
      Returns:
      true if the session is open; false otherwise.