Module ch.rasc.jcentserverclient
Package ch.rasc.jcentserverclient.clients

Interface ConnectionClient

public interface ConnectionClient
Centrifugo connection management API client.

This client provides server-side connection management capabilities, allowing you to control client subscriptions and connections from your backend. These operations are particularly useful for implementing server-side subscriptions and connection lifecycle management.

Key features:

  • Server-side subscription management
  • Client disconnection control
  • Connection refresh for unidirectional transports
  • Channel option overrides
  • Session and client-specific targeting
Since:
1.0.0
See Also:

  • Method Details

    • subscribe

      SubscribeResponse subscribe(SubscribeRequest request)
      Subscribe a user to a channel.

      Creates a server-side subscription for a user to a specific channel. This is not a real-time streaming subscription request, but a command to subscribe online user sessions to a channel from the server side.

      Use cases:

      • Dynamic server-side subscriptions
      • Auto-subscribing users to relevant channels
      • Subscription with custom channel info
      • Recovery from specific stream positions

      Features:

      • Custom subscription data and info
      • Channel option overrides (presence, join/leave, etc.)
      • Stream position recovery
      • Client or session-specific targeting

      Example: 

      
 SubscribeRequest request = SubscribeRequest.builder().user("user123")
 		.channel("notifications:user123").info(Map.of("role", "subscriber"))
 		.build();

 SubscribeResponse response = client.subscribe(request);
      Parameters:
      request - the subscribe request containing user, channel, and subscription options
      Returns:
      the subscribe response
      See Also:

    • subscribe

      default SubscribeResponse subscribe(Function<SubscribeRequest.Builder,SubscribeRequest.Builder> fn)
      Subscribe a user to a channel.

      Creates a server-side subscription for a user to a specific channel. This is not a real-time streaming subscription request, but a command to subscribe online user sessions to a channel from the server side.

      Use cases:

      • Dynamic server-side subscriptions
      • Auto-subscribing users to relevant channels
      • Subscription with custom channel info
      • Recovery from specific stream positions

      Features:

      • Custom subscription data and info
      • Channel option overrides (presence, join/leave, etc.)
      • Stream position recovery
      • Client or session-specific targeting

      Example: 

      
 SubscribeRequest request = SubscribeRequest.builder().user("user123")
 		.channel("notifications:user123").info(Map.of("role", "subscriber"))
 		.build();

 SubscribeResponse response = client.subscribe(request);
      Parameters:
      fn - the function to configure the subscribe request
      Returns:
      the subscribe response
      See Also:

    • unsubscribe

      UnsubscribeResponse unsubscribe(UnsubscribeRequest request)
      Unsubscribe a user from a channel.

      Removes a user's subscription to a specific channel. Can target all user connections or specific client/session connections.

      Targeting options:

      • All user connections (by user ID only)
      • Specific client connection
      • Specific session

      Example: 

      
 UnsubscribeRequest request = UnsubscribeRequest.builder().user("user123")
 		.channel("notifications:user123").build();

 UnsubscribeResponse response = client.unsubscribe(request);
      Parameters:
      request - the unsubscribe request containing user, channel, and optional client/session targeting
      Returns:
      the unsubscribe response
      See Also:

    • unsubscribe

      default UnsubscribeResponse unsubscribe(Function<UnsubscribeRequest.Builder,UnsubscribeRequest.Builder> fn)
      Unsubscribe a user from a channel.

      Removes a user's subscription to a specific channel. Can target all user connections or specific client/session connections.

      Targeting options:

      • All user connections (by user ID only)
      • Specific client connection
      • Specific session

      Example: 

      
 UnsubscribeRequest request = UnsubscribeRequest.builder().user("user123")
 		.channel("notifications:user123").build();

 UnsubscribeResponse response = client.unsubscribe(request);
      Parameters:
      fn - the function to configure the unsubscribe request
      Returns:
      the unsubscribe response
      See Also:

    • disconnect

      DisconnectResponse disconnect(DisconnectRequest request)
      Disconnect a user.

      Forcibly disconnects user connections from the server. Useful for implementing user bans, session management, or forcing re-authentication.

      Disconnect targeting:

      • All user connections
      • Specific client connection
      • Specific session
      • All except whitelisted clients

      Supports custom disconnect codes and reasons for client-side handling.

      Example: 

      
 DisconnectRequest request = DisconnectRequest.builder().user("user123")
 		.disconnect(Disconnect.builder().code(4000).reason("User banned").build())
 		.build();

 DisconnectResponse response = client.disconnect(request);
      Parameters:
      request - the disconnect request containing user targeting and disconnect options
      Returns:
      the disconnect response
      See Also:

    • disconnect

      default DisconnectResponse disconnect(Function<DisconnectRequest.Builder,DisconnectRequest.Builder> fn)
      Disconnect a user.

      Forcibly disconnects user connections from the server. Useful for implementing user bans, session management, or forcing re-authentication.

      Disconnect targeting:

      • All user connections
      • Specific client connection
      • Specific session
      • All except whitelisted clients

      Supports custom disconnect codes and reasons for client-side handling.

      Example: 

      
 DisconnectRequest request = DisconnectRequest.builder().user("user123")
 		.disconnect(Disconnect.builder().code(4000).reason("User banned").build())
 		.build();

 DisconnectResponse response = client.disconnect(request);
      Parameters:
      fn - the function to configure the disconnect request
      Returns:
      the disconnect response
      See Also:

    • refresh

      RefreshResponse refresh(RefreshRequest request)
      Refresh a user connection.

      Refreshes user connections, primarily useful for unidirectional transports or when you need to update connection metadata. Can mark connections as expired or set new expiration times.

      Use cases:

      • Refreshing unidirectional transport connections
      • Updating connection expiration times
      • Marking connections as expired
      • Triggering connection state updates

      Example: 

      
 RefreshRequest request = RefreshRequest.builder().user("user123")
 		.expireAt(System.currentTimeMillis() / 1000 + 3600) // 1 hour from now
 		.build();

 RefreshResponse response = client.refresh(request);
      Parameters:
      request - the refresh request containing user targeting and refresh options
      Returns:
      the refresh response
      See Also:

    • refresh

      default RefreshResponse refresh(Function<RefreshRequest.Builder,RefreshRequest.Builder> fn)
      Refresh a user connection.

      Refreshes user connections, primarily useful for unidirectional transports or when you need to update connection metadata. Can mark connections as expired or set new expiration times.

      Use cases:

      • Refreshing unidirectional transport connections
      • Updating connection expiration times
      • Marking connections as expired
      • Triggering connection state updates

      Example: 

      
 RefreshRequest request = RefreshRequest.builder().user("user123")
 		.expireAt(System.currentTimeMillis() / 1000 + 3600) // 1 hour from now
 		.build();

 RefreshResponse response = client.refresh(request);
      Parameters:
      fn - the function to configure the refresh request
      Returns:
      the refresh response
      See Also: