Package io.ably.lib.rest

Class ChannelBase

java.lang.Object
io.ably.lib.rest.ChannelBase
Direct Known Subclasses:
Channel
public class ChannelBase extends Object
A class representing a Channel in the Ably REST API. In the REST API, the library is essentially stateless; a Channel object simply represents a channel for making REST requests, and existence of a channel does not signify that there is a realtime connection or attachment to that channel.

  • Field Details

    • name

      public final String name
      The Channel name

    • presence

      public final ChannelBase.Presence presence
      The presence instance for this channel.

    • annotations

      public final RestAnnotations annotations
      Represents the annotations associated with a channel message. This field provides functionality for managing annotations.

  • Method Details

    • publish

      @Blocking public void publish(String name, Object data) throws AblyException
      Publish a message on this channel using the REST API. Since the REST API is stateless, this request is made independently of any other request on this or any other channel.
      Parameters:
      name - the event name
      data - the message payload;
      Throws:
      AblyException

    • publishWithResult

      @Blocking public PublishResult publishWithResult(String name, Object data) throws AblyException
      Publish a message on this channel using the REST API and return the result. Since the REST API is stateless, this request is made independently of any other request on this or any other channel.
      Parameters:
      name - the event name
      data - the message payload;
      Returns:
      A PublishResult containing the message serial(s)
      Throws:
      AblyException

    • publishAsync

      @Deprecated public void publishAsync(String name, Object data, CompletionListener listener)
      Deprecated.
      Use publishAsync(String, Object, Callback) instead.
      Publish a message on this channel using the REST API. Since the REST API is stateless, this request is made independently of any other request on this or any other channel.
      Parameters:
      name - the event name
      data - the message payload;
      listener - a listener to be notified of the outcome of this message.

      This listener is invoked on a background thread.

    • publishAsync

      @NonBlocking public void publishAsync(String name, Object data, Callback<PublishResult> callback)
      Asynchronously publish a message on this channel using the REST API. Since the REST API is stateless, this request is made independently of any other request on this or any other channel.
      Parameters:
      name - the event name
      data - the message payload;
      callback - a callback to be notified of the outcome of this message with the PublishResult.

      This callback is invoked on a background thread.

    • publish

      @Blocking public void publish(Message[] messages) throws AblyException
      Publish an array of messages on this channel. When there are multiple messages to be sent, it is more efficient to use this method to publish them in a single request, as compared with publishing via multiple independent requests.
      Parameters:
      messages - array of messages to publish.
      Throws:
      AblyException

    • publishWithResult

      @Blocking public PublishResult publishWithResult(Message[] messages) throws AblyException
      Publish an array of messages on this channel. When there are multiple messages to be sent, it is more efficient to use this method to publish them in a single request, as compared with publishing via multiple independent requests.
      Parameters:
      messages - array of messages to publish.
      Throws:
      AblyException

    • publishAsync

      @Deprecated @NonBlocking public void publishAsync(Message[] messages, CompletionListener listener)
      Deprecated.
      Use publishAsync(Message[], Callback) instead.

      This listener is invoked on a background thread.

      Asynchronously publish an array of messages on this channel
      Parameters:
      messages - the message
      listener - a listener to be notified of the outcome of this message.

    • publishAsync

      @NonBlocking public void publishAsync(Message[] messages, Callback<PublishResult> callback)
      Asynchronously publish an array of messages on this channel
      Parameters:
      messages - the message
      callback - a callback to be notified of the outcome of this message.

      This callback is invoked on a background thread.

    • history

      public PaginatedResult<Message> history(Param[] params) throws AblyException
      Obtain recent history for this channel using the REST API. The history provided relqtes to all clients of this application, not just this instance.
      Parameters:
      params - the request params. See the Ably REST API documentation for more details.
      Returns:
      an array of Messages for this Channel.
      Throws:
      AblyException

    • historyAsync

      public void historyAsync(Param[] params, Callback<AsyncPaginatedResult<Message>> callback)
      Asynchronously obtain recent history for this channel using the REST API.
      Parameters:
      params - the request params. See the Ably REST API
      callback -

    • getMessage

      @Blocking public Message getMessage(String serial) throws AblyException
      Retrieves the latest version of a specific message by its serial identifier.

      This method allows you to fetch the current state of a message, including any updates or deletions that have been applied since its creation.

      Parameters:
      serial - The unique serial identifier of the message to retrieve.
      Returns:
      A Message object representing the latest version of the message.
      Throws:
      AblyException - If the message cannot be retrieved or does not exist.

    • getMessageAsync

      @NonBlocking public void getMessageAsync(String serial, Callback<Message> callback)
      Asynchronously retrieves the latest version of a specific message by its serial identifier.
      Parameters:
      serial - The unique serial identifier of the message to retrieve.
      callback - A callback to handle the result asynchronously.

      This callback is invoked on a background thread.

    • updateMessage

      @Blocking public UpdateDeleteResult updateMessage(Message message, MessageOperation operation) throws AblyException
      Updates an existing message using patch semantics.

      Non-null fields in the provided message (name, data, extras) will replace the corresponding fields in the existing message, while null fields will be left unchanged.

      Parameters:
      message - A Message object containing the fields to update and the serial identifier. Only non-null fields will be applied to the existing message.
      operation - operation metadata such as clientId, description, or metadata in the version field
      Returns:
      A UpdateDeleteResult containing the updated message version serial.
      Throws:
      AblyException - If the update operation fails.

    • updateMessage

      @Blocking public UpdateDeleteResult updateMessage(Message message) throws AblyException
      Updates an existing message using patch semantics.

      Non-null fields in the provided message (name, data, extras) will replace the corresponding fields in the existing message, while null fields will be left unchanged.

      Parameters:
      message - A Message object containing the fields to update and the serial identifier. Only non-null fields will be applied to the existing message.
      Returns:
      A UpdateDeleteResult containing the updated message version serial.
      Throws:
      AblyException - If the update operation fails.

    • updateMessageAsync

      @NonBlocking public void updateMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)
      Asynchronously updates an existing message.
      Parameters:
      message - A Message object containing the fields to update and the serial identifier.
      operation - operation metadata such as clientId, description, or metadata in the version field
      callback - A callback to be notified of the outcome of this operation.

      This callback is invoked on a background thread.

    • updateMessageAsync

      @NonBlocking public void updateMessageAsync(Message message, Callback<UpdateDeleteResult> callback)
      Asynchronously updates an existing message.
      Parameters:
      message - A Message object containing the fields to update and the serial identifier.
      callback - A callback to be notified of the outcome of this operation.

      This callback is invoked on a background thread.

    • deleteMessage

      @Blocking public UpdateDeleteResult deleteMessage(Message message, MessageOperation operation) throws AblyException
      Marks a message as deleted.

      This operation does not remove the message from history; it marks it as deleted while preserving the full message history. The deleted message can still be retrieved and will have its action set to MESSAGE_DELETE.

      Parameters:
      message - A Message message containing the serial identifier.
      operation - operation metadata such as clientId, description, or metadata in the version field
      Returns:
      A UpdateDeleteResult containing the deleted message version serial.
      Throws:
      AblyException - If the delete operation fails.

    • deleteMessage

      @Blocking public UpdateDeleteResult deleteMessage(Message message) throws AblyException
      Marks a message as deleted.

      This operation does not remove the message from history; it marks it as deleted while preserving the full message history. The deleted message can still be retrieved and will have its action set to MESSAGE_DELETE.

      Parameters:
      message - A Message message containing the serial identifier.
      Returns:
      A UpdateDeleteResult containing the deleted message version serial.
      Throws:
      AblyException - If the delete operation fails.

    • deleteMessageAsync

      @NonBlocking public void deleteMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)
      Asynchronously marks a message as deleted.
      Parameters:
      message - A Message object containing the serial identifier and operation metadata.
      operation - operation metadata such as clientId, description, or metadata in the version field
      callback - A callback to be notified of the outcome of this operation.

      This callback is invoked on a background thread.

    • deleteMessageAsync

      @NonBlocking public void deleteMessageAsync(Message message, Callback<UpdateDeleteResult> callback)
      Asynchronously marks a message as deleted.
      Parameters:
      message - A Message object containing the serial identifier and operation metadata.
      callback - A callback to be notified of the outcome of this operation.

      This callback is invoked on a background thread.

    • appendMessage

      @Blocking public UpdateDeleteResult appendMessage(Message message, MessageOperation operation) throws AblyException
      Appends message text to the end of the message.
      Parameters:
      message - A Message object containing the serial identifier and data to append.
      operation - operation details such as clientId, description, or metadata
      Returns:
      A UpdateDeleteResult containing the updated message version serial.
      Throws:
      AblyException - If the append operation fails.

    • appendMessage

      @Blocking public UpdateDeleteResult appendMessage(Message message) throws AblyException
      Appends message text to the end of the message.
      Parameters:
      message - A Message object containing the serial identifier and data to append.
      Returns:
      A UpdateDeleteResult containing the updated message version serial.
      Throws:
      AblyException - If the append operation fails.

    • appendMessageAsync

      @NonBlocking public void appendMessageAsync(Message message, MessageOperation operation, Callback<UpdateDeleteResult> callback)
      Asynchronously appends message text to the end of the message.
      Parameters:
      message - A Message object containing the serial identifier and data to append.
      operation - operation details such as clientId, description, or metadata
      callback - A callback to be notified of the outcome of this operation.

      This callback is invoked on a background thread.

    • appendMessageAsync

      @NonBlocking public void appendMessageAsync(Message message, Callback<UpdateDeleteResult> callback)
      Asynchronously appends message text to the end of the message.
      Parameters:
      message - A Message object containing the serial identifier and data to append.
      callback - A callback to be notified of the outcome of this operation.

      This callback is invoked on a background thread.

    • getMessageVersions

      @Blocking public PaginatedResult<Message> getMessageVersions(String serial, Param[] params) throws AblyException
      Retrieves all historical versions of a specific message.

      This method returns a paginated result containing all versions of the message, ordered chronologically. Each version includes metadata about when and by whom the message was modified.

      Parameters:
      serial - The unique serial identifier of the message.
      params - Query parameters for filtering or pagination (e.g., limit, start, end).
      Returns:
      A PaginatedResult containing an array of Message objects representing all versions of the message.
      Throws:
      AblyException - If the versions cannot be retrieved.

    • getMessageVersionsAsync

      @NonBlocking public void getMessageVersionsAsync(String serial, Param[] params, Callback<AsyncPaginatedResult<Message>> callback) throws AblyException
      Asynchronously retrieves all historical versions of a specific message.
      Parameters:
      serial - The unique serial identifier of the message.
      params - Query parameters for filtering or pagination.
      callback - A callback to handle the result asynchronously.
      Throws:
      AblyException