Package io.ably.lib.realtime

Class Presence

java.lang.Object
io.ably.lib.realtime.Presence
public class Presence extends Object
Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel.

  • Field Details

    • GET_WAITFORSYNC

      public static final String GET_WAITFORSYNC
      String parameter names for get() call with Param... as an argument
      See Also:

    • GET_CLIENTID

      public static final String GET_CLIENTID
      See Also:

    • GET_CONNECTIONID

      public static final String GET_CONNECTIONID
      See Also:

    • syncComplete

      public boolean syncComplete
      Indicates whether the presence set synchronization between Ably and the clients on the channel has been completed. Set to true when the sync is complete.

      Spec: RTP13

  • Method Details

    • get

      public PresenceMessage[] get(Param... params) throws AblyException
      Retrieves the current members present on the channel and the metadata for each member, such as their PresenceMessage.Action and ID. Returns an array of PresenceMessage objects.

      Spec: RTP11

      Parameters:
      params - the request params:

      waitForSync (RTP11c1) - Sets whether to wait for a full presence set synchronization between Ably and the clients on the channel to complete before returning the results. Synchronization begins as soon as the channel is ChannelState.attached. When set to true the results will be returned as soon as the sync is complete. When set to false the current list of members will be returned without the sync completing. The default is true.

      clientId (RTP11c2) - Filters the array of returned presence members by a specific client using its ID.

      connectionId (RTP11c3) - Filters the array of returned presence members by a specific connection using its ID.

      Returns:
      An array of PresenceMessage objects.
      Throws:
      AblyException

    • get

      public PresenceMessage[] get(boolean wait) throws AblyException
      Retrieves the current members present on the channel and the metadata for each member, such as their PresenceMessage.Action and ID. Returns an array of PresenceMessage objects.

      Spec: RTP11

      Parameters:
      wait - (RTP11c1) - Sets whether to wait for a full presence set synchronization between Ably and the clients on the channel to complete before returning the results. Synchronization begins as soon as the channel is ChannelState.attached. When set to true the results will be returned as soon as the sync is complete. When set to false the current list of members will be returned without the sync completing. The default is true.
      Returns:
      An array of PresenceMessage objects.
      Throws:
      AblyException

    • get

      public PresenceMessage[] get(String clientId, boolean wait) throws AblyException
      Retrieves the current members present on the channel and the metadata for each member, such as their PresenceMessage.Action and ID. Returns an array of PresenceMessage objects.

      Spec: RTP11

      Parameters:
      clientId - (RTP11c2) - Filters the array of returned presence members by a specific client using its ID.
      wait - (RTP11c1) - Sets whether to wait for a full presence set synchronization between Ably and the clients on the channel to complete before returning the results. Synchronization begins as soon as the channel is ChannelState.attached. When set to true the results will be returned as soon as the sync is complete. When set to false the current list of members will be returned without the sync completing. The default is true.
      Returns:
      An array of PresenceMessage objects.
      Throws:
      AblyException

    • subscribe

      public void subscribe(Presence.PresenceListener listener, CompletionListener completionListener) throws AblyException
      Registers a listener that is called each time a PresenceMessage matching a given PresenceMessage.Action, or an action within an array of PresenceMessage.Action, is received on the channel, such as a new member entering the presence set.

      Spec: RTP6a

      Parameters:
      listener - An event listener function.
      completionListener - A callback to be notified of success or failure of the channel ChannelBase.attach() operation.

      These listeners are invoked on a background thread.
      Throws:
      AblyException

    • subscribe

      public void subscribe(Presence.PresenceListener listener) throws AblyException
      Registers a listener that is called each time a PresenceMessage matching a given PresenceMessage.Action, or an action within an array of PresenceMessage.Action, is received on the channel, such as a new member entering the presence set.

      Spec: RTP6a

      Parameters:
      listener - An event listener function.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • unsubscribe

      public void unsubscribe(Presence.PresenceListener listener)
      Deregisters a specific listener that is registered to receive PresenceMessage on the channel.

      Spec: RTP7a

      Parameters:
      listener - An event listener function.

    • subscribe

      public void subscribe(PresenceMessage.Action action, Presence.PresenceListener listener, CompletionListener completionListener) throws AblyException
      Registers a listener that is called each time a PresenceMessage matching a given PresenceMessage.Action, or an action within an array of PresenceMessage.Action, is received on the channel, such as a new member entering the presence set.

      Spec: RTP6b

      Parameters:
      action - A PresenceMessage.Action to register the listener for.
      listener - An event listener function.
      completionListener - A callback to be notified of success or failure of the channel ChannelBase.attach() operation.

      These listeners are invoked on a background thread.
      Throws:
      AblyException

    • subscribe

      public void subscribe(PresenceMessage.Action action, Presence.PresenceListener listener) throws AblyException
      Registers a listener that is called each time a PresenceMessage matching a given PresenceMessage.Action, or an action within an array of PresenceMessage.Action, is received on the channel, such as a new member entering the presence set.

      Spec: RTP6b

      Parameters:
      action - A PresenceMessage.Action to register the listener for.
      listener - An event listener function.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • unsubscribe

      public void unsubscribe(PresenceMessage.Action action, Presence.PresenceListener listener)
      Deregisters a specific listener that is registered to receive PresenceMessage on the channel for a given PresenceMessage.Action.

      Spec: RTP7b

      Parameters:
      action - A specific PresenceMessage.Action to deregister the listener for.
      listener - An event listener function.

    • subscribe

      public void subscribe(EnumSet<PresenceMessage.Action> actions, Presence.PresenceListener listener, CompletionListener completionListener) throws AblyException
      Registers a listener that is called each time a PresenceMessage matching a given PresenceMessage.Action, or an action within an array of PresenceMessage.Action, is received on the channel, such as a new member entering the presence set.

      Spec: RTP6b

      Parameters:
      actions - An array of PresenceMessage.Action to register the listener for.
      listener - An event listener function.
      completionListener - A callback to be notified of success or failure of the channel ChannelBase.attach() operation.

      These listeners are invoked on a background thread.
      Throws:
      AblyException

    • subscribe

      public void subscribe(EnumSet<PresenceMessage.Action> actions, Presence.PresenceListener listener) throws AblyException
      Registers a listener that is called each time a PresenceMessage matching a given PresenceMessage.Action, or an action within an array of PresenceMessage.Action, is received on the channel, such as a new member entering the presence set.

      Spec: RTP6b

      Parameters:
      actions - An array of PresenceMessage.Action to register the listener for.
      listener - An event listener function.

      These listeners are invoked on a background thread.
      Throws:
      AblyException

    • unsubscribe

      public void unsubscribe(EnumSet<PresenceMessage.Action> actions, Presence.PresenceListener listener)
      Deregisters a specific listener that is registered to receive PresenceMessage on the channel for a given PresenceMessage.Action.

      Spec: RTP7b

      Parameters:
      actions - An array of specific PresenceMessage.Action to deregister the listener for.
      listener - An event listener function.

    • unsubscribe

      public void unsubscribe()
      Deregisters all listeners currently receiving PresenceMessage for the channel.

      Spec: RTP7a, RTE5

    • enter

      public void enter(Object data, CompletionListener listener) throws AblyException
      Enters the presence set for the channel, optionally passing a data payload. A clientId is required to be present on a channel. An optional callback may be provided to notify of the success or failure of the operation.

      Spec: RTP8

      Parameters:
      data - The payload associated with the presence member.
      listener - An callback to notify of the success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • update

      public void update(Object data, CompletionListener listener) throws AblyException
      Updates the data payload for a presence member. If called before entering the presence set, this is treated as an PresenceMessage.Action.enter event. An optional callback may be provided to notify of the success or failure of the operation.

      Spec: RTP9

      Parameters:
      data - The payload associated with the presence member.
      listener - An callback to notify of the success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • leave

      public void leave(Object data, CompletionListener listener) throws AblyException
      Leaves the presence set for the channel. A client must have previously entered the presence set before they can leave it.

      Spec: RTP10

      Parameters:
      data - The payload associated with the presence member.
      listener - a listener to notify of the success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • leave

      public void leave(CompletionListener listener) throws AblyException
      Leaves the presence set for the channel. A client must have previously entered the presence set before they can leave it.

      Spec: RTP10

      Parameters:
      listener - a listener to notify of the success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • enterClient

      public void enterClient(String clientId) throws AblyException
      Enters the presence set of the channel for a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId.

      Spec: RTP4, RTP14, RTP15

      Parameters:
      clientId - The ID of the client to enter into the presence set.
      Throws:
      AblyException

    • enterClient

      public void enterClient(String clientId, Object data) throws AblyException
      Enters the presence set of the channel for a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId.

      Spec: RTP4, RTP14, RTP15

      Parameters:
      clientId - The ID of the client to enter into the presence set.
      data - The payload associated with the presence member.
      Throws:
      AblyException

    • enterClient

      public void enterClient(String clientId, Object data, CompletionListener listener) throws AblyException
      Enters the presence set of the channel for a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId.

      Spec: RTP4, RTP14, RTP15

      Parameters:
      clientId - The ID of the client to enter into the presence set.
      data - The payload associated with the presence member.
      listener - An callback to notify of the success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • updateClient

      public void updateClient(String clientId) throws AblyException
      Updates the data payload for a presence member using a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success or failure of the operation.

      Spec: RTP15

      Parameters:
      clientId - The ID of the client to update in the presence set.
      Throws:
      AblyException

    • updateClient

      public void updateClient(String clientId, Object data) throws AblyException
      Updates the data payload for a presence member using a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success or failure of the operation.

      Spec: RTP15

      Parameters:
      clientId - The ID of the client to update in the presence set.
      data - The payload to update for the presence member.
      Throws:
      AblyException

    • updateClient

      public void updateClient(String clientId, Object data, CompletionListener listener) throws AblyException
      Updates the data payload for a presence member using a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId. An optional callback may be provided to notify of the success or failure of the operation.

      Spec: RTP15

      Parameters:
      clientId - The ID of the client to update in the presence set.
      data - The payload to update for the presence member.
      listener - An callback to notify of the success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • leaveClient

      public void leaveClient(String clientId) throws AblyException
      Leaves the presence set of the channel for a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId.

      Spec: RTP15

      Parameters:
      clientId - The ID of the client to leave the presence set for.
      Throws:
      AblyException

    • leaveClient

      public void leaveClient(String clientId, Object data) throws AblyException
      Leaves the presence set of the channel for a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId.

      Spec: RTP15

      Parameters:
      clientId - The ID of the client to leave the presence set for.
      data - The payload associated with the presence member.
      Throws:
      AblyException

    • leaveClient

      public void leaveClient(String clientId, Object data, CompletionListener listener) throws AblyException
      Leaves the presence set of the channel for a given clientId. Enables a single client to update presence on behalf of any number of clients using a single connection. The library must have been instantiated with an API key or a token bound to a wildcard clientId.

      Spec: RTP15

      Parameters:
      clientId - The ID of the client to leave the presence set for.
      data - The payload associated with the presence member.
      listener - An callback to notify of the success or failure of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • updatePresence

      public void updatePresence(PresenceMessage msg, CompletionListener listener) throws AblyException
      Update the presence for this channel with a given PresenceMessage update. The connection must be authenticated in a way that enables it to represent the clientId in the message.
      Parameters:
      msg - the presence message
      listener - a listener to be notified on completion of the operation.

      This listener is invoked on a background thread.

      Throws:
      AblyException

    • history

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

      Spec: RTP12c

      Parameters:
      params - the request params:

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

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

      direction (RTP12a) - 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 (RTP12a) - An upper limit on the number of messages returned. The default is 100, and the maximum is 1000.

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

    • historyAsync

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

      Spec: RTP12c

      Parameters:
      params - the request params:

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

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

      direction (RTP12a) - 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 (RTP12a) - An upper limit on the number of messages returned. The default is 100, and the maximum is 1000.

      callback - A Callback returning AsyncPaginatedResult object containing an array of PresenceMessage objects.

      This callback is invoked on a background thread.

      Throws:
      AblyException