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

Interface HistoryClient

public interface HistoryClient
Centrifugo history API client for managing channel message history.

This client provides access to Centrifugo's channel history functionality, allowing you to retrieve and manage message history stored in channels. History must be enabled in channel configuration for these operations to work.

Key features:

  • Retrieve channel message history with pagination
  • Get current stream position information
  • History iteration with since/limit parameters
  • Reverse chronological ordering
  • History cleanup and removal
Since:
1.0.0
See Also:

  • Method Details

    • history

      HistoryResponse history(HistoryRequest request)
      Get channel history.

      Retrieves message history for a specific channel. By default, if no limit parameter is set, only current stream position information is returned (offset and epoch). To get actual publications, you must explicitly provide a limit parameter.

      Features:

      • Pagination with limit parameter
      • Stream position-based iteration
      • Reverse chronological ordering
      • Current stream position metadata

      Use cases:

      • Loading chat history for new participants
      • Implementing message recovery
      • Building message pagination
      • Synchronizing client state

      Example for getting recent messages: 

      
 HistoryRequest request = HistoryRequest.builder().channel("chat:room1").limit(50)
 		.reverse(true) // Get latest messages first
 		.build();

 HistoryResponse response = client.history(request);

      Example for pagination: 

      
 HistoryRequest request = HistoryRequest.builder().channel("chat:room1").limit(20)
 		.since(StreamPosition.builder().offset(100).epoch("abc123").build())
 		.build();

 HistoryResponse response = client.history(request);
      Parameters:
      request - the history request containing channel, pagination, and filtering options
      Returns:
      the history response containing publications and stream position information
      See Also:

    • history

      default HistoryResponse history(Function<HistoryRequest.Builder,HistoryRequest.Builder> fn)
      Get channel history.

      Retrieves message history for a specific channel. By default, if no limit parameter is set, only current stream position information is returned (offset and epoch). To get actual publications, you must explicitly provide a limit parameter.

      Features:

      • Pagination with limit parameter
      • Stream position-based iteration
      • Reverse chronological ordering
      • Current stream position metadata

      Use cases:

      • Loading chat history for new participants
      • Implementing message recovery
      • Building message pagination
      • Synchronizing client state

      Example for getting recent messages: 

      
 HistoryRequest request = HistoryRequest.builder().channel("chat:room1").limit(50)
 		.reverse(true) // Get latest messages first
 		.build();

 HistoryResponse response = client.history(request);

      Example for pagination: 

      
 HistoryRequest request = HistoryRequest.builder().channel("chat:room1").limit(20)
 		.since(StreamPosition.builder().offset(100).epoch("abc123").build())
 		.build();

 HistoryResponse response = client.history(request);
      Parameters:
      fn - the function to configure the history request
      Returns:
      the history response containing publications and stream position information
      See Also:

    • historyRemove

      HistoryRemoveResponse historyRemove(HistoryRemoveRequest request)
      Remove channel history.

      Removes all publications from channel history while keeping the current stream position metadata intact. This prevents client disconnects due to insufficient state while clearing historical data.

      Use cases:

      • Implementing message retention policies
      • Clearing sensitive historical data
      • Maintaining history storage limits
      • Channel cleanup operations

      Important notes:

      • Only publications are removed, stream metadata is preserved
      • Connected clients will not be disconnected
      • New publications continue normally after removal
      • Operation cannot be undone

      Example: 

      
 HistoryRemoveRequest request = HistoryRemoveRequest.builder().channel("chat:room1")
 		.build();

 HistoryRemoveResponse response = client.historyRemove(request);
      Parameters:
      request - the history remove request containing the channel to clear
      Returns:
      the history remove response
      See Also:

    • historyRemove

      default HistoryRemoveResponse historyRemove(String channel)
      Remove channel history.

      Removes all publications from channel history while keeping the current stream position metadata intact. This prevents client disconnects due to insufficient state while clearing historical data.

      Use cases:

      • Implementing message retention policies
      • Clearing sensitive historical data
      • Maintaining history storage limits
      • Channel cleanup operations

      Important notes:

      • Only publications are removed, stream metadata is preserved
      • Connected clients will not be disconnected
      • New publications continue normally after removal
      • Operation cannot be undone

      Example: 

      
 HistoryRemoveRequest request = HistoryRemoveRequest.builder().channel("chat:room1")
 		.build();

 HistoryRemoveResponse response = client.historyRemove(request);
      Parameters:
      channel - the channel to remove history from
      Returns:
      the history remove response
      See Also: