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

      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

    • publishAsync

      public void publishAsync(String name, Object data, CompletionListener listener)
      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.

    • publish

      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

    • publishAsync

      public void publishAsync(Message[] messages, CompletionListener listener)
      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.

      This listener 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

      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

      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

      public void 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
      Throws:
      AblyException - If the update operation fails.

    • updateMessage

      public void 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.
      Throws:
      AblyException - If the update operation fails.

    • updateMessageAsync

      public void updateMessageAsync(Message message, MessageOperation operation, CompletionListener listener)
      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
      listener - A listener to be notified of the outcome of this operation.

      This listener is invoked on a background thread.

    • updateMessageAsync

      public void updateMessageAsync(Message message, CompletionListener listener)
      Asynchronously updates an existing message.
      Parameters:
      message - A Message object containing the fields to update and the serial identifier.
      listener - A listener to be notified of the outcome of this operation.

      This listener is invoked on a background thread.

    • deleteMessage

      public void 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
      Throws:
      AblyException - If the delete operation fails.

    • deleteMessage

      public void 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.
      Throws:
      AblyException - If the delete operation fails.

    • deleteMessageAsync

      public void deleteMessageAsync(Message message, MessageOperation operation, CompletionListener listener)
      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
      listener - A listener to be notified of the outcome of this operation.

      This listener is invoked on a background thread.

    • deleteMessageAsync

      public void deleteMessageAsync(Message message, CompletionListener listener)
      Asynchronously marks a message as deleted.
      Parameters:
      message - A Message object containing the serial identifier and operation metadata.
      listener - A listener to be notified of the outcome of this operation.

      This listener is invoked on a background thread.

    • getMessageVersions

      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

      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