Package io.ably.lib.realtime

Class ChannelBase

java.lang.Object
io.ably.lib.util.EventEmitter<ChannelEvent,ChannelStateListener>
io.ably.lib.realtime.ChannelBase
Direct Known Subclasses:
Channel
public abstract class ChannelBase extends EventEmitter<ChannelEvent,ChannelStateListener>
Enables messages to be published and subscribed to. Also enables historic messages to be retrieved and provides access to the Presence object of a channel.

  • Field Details

  • Method Details

    • getObjects

      public RealtimeObjects getObjects() throws AblyException
      Throws:
      AblyException

    • attach

      public void attach() throws AblyException
      Attach to this channel ensuring the channel is created in the Ably system and all messages published on the channel are received by any channel listeners registered using subscribe(io.ably.lib.realtime.ChannelBase.MessageListener). Any resulting channel state change will be emitted to any listeners registered using the EventEmitter.on(Listener) or EventEmitter.once(Listener) methods. As a convenience, attach() is called implicitly if subscribe(io.ably.lib.realtime.ChannelBase.MessageListener) for the channel is called, or Presence.enter(java.lang.Object, io.ably.lib.realtime.CompletionListener) or Presence.subscribe(io.ably.lib.realtime.Presence.PresenceListener, io.ably.lib.realtime.CompletionListener) are called on the Presence object for this channel.

      Spec: RTL4d

      Throws:
      AblyException

    • attach

      public void attach(CompletionListener listener) throws AblyException
      Attach to this channel ensuring the channel is created in the Ably system and all messages published on the channel are received by any channel listeners registered using subscribe(io.ably.lib.realtime.ChannelBase.MessageListener). Any resulting channel state change will be emitted to any listeners registered using the EventEmitter.on(Listener) or EventEmitter.once(Listener) methods. As a convenience, attach() is called implicitly if subscribe(io.ably.lib.realtime.ChannelBase.MessageListener) for the channel is called, or Presence.enter(java.lang.Object, io.ably.lib.realtime.CompletionListener) or Presence.subscribe(io.ably.lib.realtime.Presence.PresenceListener, io.ably.lib.realtime.CompletionListener) are called on the Presence object for this channel.

      Spec: RTL4d

      Parameters:
      listener - A callback may optionally be passed in to this call to be notified of success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • detach

      public void detach() throws AblyException
      Detach from this channel. Any resulting channel state change is emitted to any listeners registered using the EventEmitter.on(Listener) or EventEmitter.once(Listener) methods. Once all clients globally have detached from the channel, the channel will be released in the Ably service within two minutes.

      Spec: RTL5e

      Throws:
      AblyException

    • markAsReleased

      public void markAsReleased()
      Mark channel as released that means we can't perform any operation on this channel anymore

    • detach

      public void detach(CompletionListener listener) throws AblyException
      Detach from this channel. Any resulting channel state change is emitted to any listeners registered using the EventEmitter.on(Listener) or EventEmitter.once(Listener) methods. Once all clients globally have detached from the channel, the channel will be released in the Ably service within two minutes.

      Spec: RTL5e

      Parameters:
      listener - A callback may optionally be passed in to this call to be notified of success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • sync

      @Deprecated public void sync() throws AblyException
      Deprecated.
      Throws:
      AblyException

    • setConnected

      public void setConnected()

    • setConnectionFailed

      public void setConnectionFailed(ErrorInfo reason)
      If the connection state enters the FAILED state, then an ATTACHING or ATTACHED channel state will transition to FAILED and set the Channel#errorReason

    • setConnectionClosed

      public void setConnectionClosed(ErrorInfo reason)
      (RTL3b) If the connection state enters the CLOSED state, then an ATTACHING or ATTACHED channel state will transition to DETACHED.

    • setSuspended

      public void setSuspended(ErrorInfo reason, boolean notifyStateChange)
      (RTL3c) If the connection state enters the SUSPENDED state, then an ATTACHING or ATTACHED channel state will transition to SUSPENDED. (RTN15c3) The client library should initiate an attach for channels that are in the SUSPENDED state. For all channels in the ATTACHING or ATTACHED state, the client library should fail any previously queued messages for that channel and initiate a new attach. This also gets called when a connection enters CONNECTED but with a non-fatal error for a failed reconnect (RTN16e).

    • setReinitialized

      public void setReinitialized()
      Internal

      (RTN11d) Resets channels back to initialized and clears error reason

    • apply

      protected void apply(ChannelStateListener listener, ChannelEvent event, Object... args)
      Specified by:
      apply in class EventEmitter<ChannelEvent,ChannelStateListener>

    • unsubscribe

      public void unsubscribe()
      Deregisters all listeners to messages on this channel. This removes all earlier subscriptions.

      Spec: RTL8a, RTE5

    • attachOnSubscribeEnabled

      protected boolean attachOnSubscribeEnabled()

      Checks if ChannelOptions.attachOnSubscribe is true.

      Defaults to true when options is null.

      Spec: TB4, RTL7g, RTL7h, RTP6d, RTP6e

    • subscribe

      public void subscribe(ChannelBase.MessageListener listener) throws AblyException
      Registers a listener for messages on this channel. The caller supplies a listener function, which is called each time one or more messages arrives on the channel.

      Spec: RTL7a

      Parameters:
      listener - A listener may optionally be passed in to this call to be notified of success or failure of the channel attach() operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • unsubscribe

      public void unsubscribe(ChannelBase.MessageListener listener)
      Deregisters the given listener (for any/all event names). This removes an earlier subscription.

      Spec: RTL8a

      Parameters:
      listener - An event listener function.

      This listener is invoked on a background thread.

    • subscribe

      public void subscribe(String name, ChannelBase.MessageListener listener) throws AblyException
      Registers a listener for messages with a given event name on this channel. The caller supplies a listener function, which is called each time one or more matching messages arrives on the channel.

      Spec: RTL7b

      Parameters:
      name - The event name.
      listener - A listener may optionally be passed in to this call to be notified of success or failure of the channel attach() operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • unsubscribe

      public void unsubscribe(String name, ChannelBase.MessageListener listener)
      Deregisters the given listener for the specified event name. This removes an earlier event-specific subscription

      Spec: RTL8a

      Parameters:
      name - The event name.
      listener - An event listener function.

      This listener is invoked on a background thread.

    • subscribe

      public void subscribe(String[] names, ChannelBase.MessageListener listener) throws AblyException
      Registers a listener for messages on this channel for multiple event name values. The caller supplies a listener function, which is called each time one or more matching messages arrives on the channel.

      Spec: RTL7a

      Parameters:
      names - An array of event names.
      listener - A listener may optionally be passed in to this call to be notified of success or failure of the channel attach() operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • unsubscribe

      public void unsubscribe(String[] names, ChannelBase.MessageListener listener)
      Deregisters the given listener from all event names in the array.

      Spec: RTL8a

      Parameters:
      names - An array of event names.
      listener - An event listener function.

      This listener is invoked on a background thread.

    • publish

      public void publish(String name, Object data) throws AblyException
      Publishes a single message to the channel with the given event name and payload. When publish is called with this client library, it won't attempt to implicitly attach to the channel, so long as transient publishing is available in the library. Otherwise, the client will implicitly attach.

      Spec: RTL6i

      Parameters:
      name - the event name
      data - the message payload
      Throws:
      AblyException

    • publish

      public void publish(Message message) throws AblyException
      Publishes a message to the channel. When publish is called with this client library, it won't attempt to implicitly attach to the channel.

      Spec: RTL6i

      Parameters:
      message - A Message object.
      Throws:
      AblyException

    • publish

      public void publish(Message[] messages) throws AblyException
      Publishes an array of messages to the channel. When publish is called with this client library, it won't attempt to implicitly attach to the channel.

      Spec: RTL6i

      Parameters:
      messages - An array of Message objects.
      Throws:
      AblyException

    • publish

      public void publish(String name, Object data, CompletionListener listener) throws AblyException
      Publishes a single message to the channel with the given event name and payload. When publish is called with this client library, it won't attempt to implicitly attach to the channel, so long as transient publishing is available in the library. Otherwise, the client will implicitly attach.

      Spec: RTL6i

      Parameters:
      name - the event name
      data - the message payload
      listener - A listener may optionally be passed in to this call to be notified of success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • publish

      public void publish(Message message, CompletionListener listener) throws AblyException
      Publishes a message to the channel. When publish is called with this client library, it won't attempt to implicitly attach to the channel.

      Spec: RTL6i

      Parameters:
      message - A Message object.
      listener - A listener may optionally be passed in to this call to be notified of success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • publish

      public void publish(Message[] messages, CompletionListener listener) throws AblyException
      Publishes an array of messages to the channel. When publish is called with this client library, it won't attempt to implicitly attach to the channel.

      Spec: RTL6i

      Parameters:
      messages - An array of Message objects.
      listener - A listener may optionally be passed in to this call to be notified of success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • 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

    • history

      public PaginatedResult<Message> history(Param[] params) throws AblyException
      Retrieves a PaginatedResult object, containing an array of historical Message objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past.

      Spec: RSL2a

      Parameters:
      params - the request params:

      start (RTL10a) - The time from which messages are retrieved, specified as milliseconds since the Unix epoch.

      end (RTL10a) - The time until messages are retrieved, specified as milliseconds since the Unix epoch.

      direction (RTL10a) - The order for which messages are returned in. Valid values are backwards which orders messages from most recent to oldest, or forwards which orders messages from oldest to most recent. The default is backwards.

      limit (RTL10a) - An upper limit on the number of messages returned. The default is 100, and the maximum is 1000.

      untilAttach (RTL10b) - When true, ensures message history is up until the point of the channel being attached. See continuous history for more info. Requires the direction to be backwards. If the channel is not attached, or if direction is set to forwards, this option results in an error.

      Returns:
      A PaginatedResult object containing an array of Message objects.
      Throws:
      AblyException

    • historyAsync

      public void historyAsync(Param[] params, Callback<AsyncPaginatedResult<Message>> callback)
      Asynchronously retrieves a PaginatedResult object, containing an array of historical Message objects for the channel. If the channel is configured to persist messages, then messages can be retrieved from history for up to 72 hours in the past. If not, messages can only be retrieved from history for up to two minutes in the past.

      Spec: RSL2a

      Parameters:
      params - the request params:

      start (RTL10a) - The time from which messages are retrieved, specified as milliseconds since the Unix epoch.

      end (RTL10a) - The time until messages are retrieved, specified as milliseconds since the Unix epoch.

      direction (RTL10a) - The order for which messages are returned in. Valid values are backwards which orders messages from most recent to oldest, or forwards which orders messages from oldest to most recent. The default is backwards.

      limit (RTL10a) - An upper limit on the number of messages returned. The default is 100, and the maximum is 1000.

      untilAttach (RTL10b) - When true, ensures message history is up until the point of the channel being attached. See continuous history for more info. Requires the direction to be backwards. If the channel is not attached, or if direction is set to forwards, this option results in an error.

      callback - Callback with AsyncPaginatedResult object containing an array of Message objects.
      Throws:
      AblyException

    • setOptions

      public void setOptions(ChannelOptions options) throws AblyException
      Sets the ChannelOptions for the channel.

      Spec: RTL16

      Parameters:
      options - A ChannelOptions object.
      Throws:
      AblyException

    • setOptions

      public void setOptions(ChannelOptions options, CompletionListener listener) throws AblyException
      Sets the ChannelOptions for the channel.

      Spec: RTL16

      Parameters:
      options - A ChannelOptions object.
      listener - An optional listener may be provided to notify of the success or failure of the operation.
      Throws:
      AblyException

    • getParams

      public Map<String,String> getParams()

    • getModes

      public ChannelMode[] getModes()

    • getOptions

      public ChannelOptions getOptions()

    • emit

      public void emit(ChannelState state, ChannelStateListener.ChannelStateChange channelStateChange)

    • on

      public void on(ChannelState state, ChannelStateListener listener)

    • once

      public void once(ChannelState state, ChannelStateListener listener)

    • sendProtocolMessage

      public void sendProtocolMessage(ProtocolMessage protocolMessage, CompletionListener listener) throws AblyException
      (Internal) Sends a protocol message and provides a callback for completion.
      Parameters:
      protocolMessage - the protocol message to be sent
      listener - the listener to be notified upon completion of the message delivery
      Throws:
      AblyException