Package io.github.centrifugal.centrifuge

Class Client

java.lang.Object
io.github.centrifugal.centrifuge.Client
public class Client extends Object

  • Constructor Details

    • Client

      public Client(String endpoint, Options opts, EventListener listener)
      Creates a new instance of Client. Client allows to allocate new Subscriptions to channels, automatically manages reconnects and re-subscriptions on temporary failures.
      Parameters:
      endpoint - : connection endpoint.
      opts - : client options.
      listener - : client event handler.

  • Method Details

    • getState

      public ClientState getState()

    • connect

      public void connect()
      Start connecting to a server.

    • disconnect

      public void disconnect()
      Disconnect from server and do not reconnect.

    • setToken

      public void setToken(String token)
      setToken allows updating connection token.

    • close

      public boolean close(long awaitMilliseconds) throws InterruptedException
      Close disconnects client from server and cleans up client resources including shutdown of internal executors. Client is not usable after calling this method. If you only need to temporary disconnect from server use .disconnect() method.
      Parameters:
      awaitMilliseconds - is time in milliseconds to wait for executor termination (0 means no waiting).
      Returns:
      boolean that indicates whether executor terminated in awaitMilliseconds. For zero awaitMilliseconds close always returns false.
      Throws:
      InterruptedException

    • newSubscription

      public Subscription newSubscription(String channel, SubscriptionOptions options, SubscriptionEventListener listener) throws DuplicateSubscriptionException
      Create new subscription to channel with SubscriptionOptions and SubscriptionEventListener.

      Offset persistence is enabled automatically. The SDK saves stream offsets to disk and recovers from them on restart, ensuring no messages are lost.

      Default offset storage locations:

      • macOS: ~/Library/Application Support/centrifugo/offsets/
      • Linux: ~/.local/share/centrifugo/offsets/
      • Windows: %APPDATA%/centrifugo/offsets/

      With automatic fallback to temp directory or current directory if needed.

      IMPORTANT: If you run multiple client processes on the same machine subscribing to the same channel, each process MUST use a different offsetStorageDir via SubscriptionOptions.setOffsetStorageDir(String) to avoid overwriting each other's offsets. Example:

      
 // Process 1
 SubscriptionOptions opts = new SubscriptionOptions();
 opts.setOffsetStorageDir("/data/offsets/worker-1");
 Subscription sub = client.newSubscription("my-channel", opts, listener);

 // Process 2
 SubscriptionOptions opts = new SubscriptionOptions();
 opts.setOffsetStorageDir("/data/offsets/worker-2");
 Subscription sub = client.newSubscription("my-channel", opts, listener);
      Parameters:
      channel - channel to create Subscription for.
      options - SubscriptionOptions, e.g. token, offsetStorageDir.
      listener - event handler for subscription events.
      Returns:
      Subscription.
      Throws:
      DuplicateSubscriptionException - if Subscription already exists in internal registry.

    • newSubscription

      public Subscription newSubscription(String channel, SubscriptionEventListener listener) throws DuplicateSubscriptionException
      Create new subscription to channel with SubscriptionEventListener, see also overloaded newSubscription which allows setting SubscriptionOptions
      Parameters:
      channel - : to create Subscription for.
      listener - : to pass event handler.
      Returns:
      Subscription.
      Throws:
      DuplicateSubscriptionException - if Subscription already exists in internal registry.

    • getSubscription

      public Subscription getSubscription(String channel)
      Try to get Subscription from internal client registry. Can return null if Subscription does not exist yet.
      Parameters:
      channel - : channel to get subscription for.
      Returns:
      Subscription

    • removeSubscription

      public void removeSubscription(Subscription sub)
      Say Client that Subscription should be removed from internal registry. Subscription will be automatically unsubscribed before removing.
      Parameters:
      sub - : Subscription to remove from registry.

    • send

      public void send(byte[] data, CompletionCallback cb)
      Send asynchronous message with data to server. Callback successfully completes if data written to connection. No reply from server expected in this case.
      Parameters:
      data - : custom data to publish.
      cb - : will be called as soon as data sent to the connection or error happened.

    • rpc

      public void rpc(String method, byte[] data, ResultCallback<RPCResult> cb)
      Send RPC with method to server, process result in callback.
      Parameters:
      method - : of RPC call.
      data - : a custom payload for RPC call.
      cb - : will be called as soon as rpc response received or error happened.

    • publish

      public void publish(String channel, byte[] data, ResultCallback<PublishResult> cb)
      Publish data to channel without being subscribed to it. Publish option should be enabled in Centrifuge/Centrifugo server configuration.
      Parameters:
      channel - : to publish into.
      data - : to publish.
      cb - : will be called as soon as publish response received or error happened.

    • history

      public void history(String channel, HistoryOptions opts, ResultCallback<HistoryResult> cb)
      History can get channel publication history (useful for server-side subscriptions).
      Parameters:
      channel - : to get history for.
      opts - : for history request.
      cb - : will be called as soon as response receive or error happened.

    • presence

      public void presence(String channel, ResultCallback<PresenceResult> cb)

    • presenceStats

      public void presenceStats(String channel, ResultCallback<PresenceStatsResult> cb)