Package io.ably.lib.realtime

Class Presence

java.lang.Object

io.ably.lib.realtime.Presence

public class Presence
extends java.lang.Object

Enables the presence set to be entered and subscribed to, and the historic presence set to be retrieved for a channel.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Presence.PresenceListener	An interface allowing a listener to be notified of arrival of a presence message.

Field Summary

Fields

Modifier and Type	Field	Description
static java.lang.String	GET_CLIENTID
static java.lang.String	GET_CONNECTIONID
static java.lang.String	GET_WAITFORSYNC	String parameter names for get() call with Param...
boolean	syncComplete	Indicates whether the presence set synchronization between Ably and the clients on the channel has been completed.

Method Summary

Modifier and Type	Method	Description
void	enter(java.lang.Object data, CompletionListener listener)	Enters the presence set for the channel, optionally passing a data payload.
void	enterClient(java.lang.String clientId)	Enters the presence set of the channel for a given clientId.
void	enterClient(java.lang.String clientId, java.lang.Object data)	Enters the presence set of the channel for a given clientId.
void	enterClient(java.lang.String clientId, java.lang.Object data, CompletionListener listener)	Enters the presence set of the channel for a given clientId.
PresenceMessage[]	get(boolean wait)	Retrieves the current members present on the channel and the metadata for each member, such as their PresenceMessage.Action and ID.
PresenceMessage[]	get(Param... params)	Retrieves the current members present on the channel and the metadata for each member, such as their PresenceMessage.Action and ID.
PresenceMessage[]	get(java.lang.String clientId, boolean wait)	Retrieves the current members present on the channel and the metadata for each member, such as their PresenceMessage.Action and ID.
PaginatedResult<PresenceMessage>	history(Param[] params)	Retrieves a PaginatedResult object, containing an array of historical PresenceMessage objects for the channel.
void	historyAsync(Param[] params, Callback<AsyncPaginatedResult<PresenceMessage>> callback)	Asynchronously retrieves a PaginatedResult object, containing an array of historical PresenceMessage objects for the channel.
void	leave(CompletionListener listener)	Leaves the presence set for the channel.
void	leave(java.lang.Object data, CompletionListener listener)	Leaves the presence set for the channel.
void	leaveClient(java.lang.String clientId)	Leaves the presence set of the channel for a given clientId.
void	leaveClient(java.lang.String clientId, java.lang.Object data)	Leaves the presence set of the channel for a given clientId.
void	leaveClient(java.lang.String clientId, java.lang.Object data, CompletionListener listener)	Leaves the presence set of the channel for a given clientId.
void	subscribe(Presence.PresenceListener listener)	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.
void	subscribe(Presence.PresenceListener listener, CompletionListener completionListener)	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.
void	subscribe(PresenceMessage.Action action, Presence.PresenceListener listener)	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.
void	subscribe(PresenceMessage.Action action, Presence.PresenceListener listener, CompletionListener completionListener)	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.
void	subscribe(java.util.EnumSet<PresenceMessage.Action> actions, Presence.PresenceListener listener)	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.
void	subscribe(java.util.EnumSet<PresenceMessage.Action> actions, Presence.PresenceListener listener, CompletionListener completionListener)	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.
void	unsubscribe()	Deregisters all listeners currently receiving PresenceMessage for the channel.
void	unsubscribe(Presence.PresenceListener listener)	Deregisters a specific listener that is registered to receive PresenceMessage on the channel.
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.
void	unsubscribe(java.util.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.
void	update(java.lang.Object data, CompletionListener listener)	Updates the data payload for a presence member.
void	updateClient(java.lang.String clientId)	Updates the data payload for a presence member using a given clientId.
void	updateClient(java.lang.String clientId, java.lang.Object data)	Updates the data payload for a presence member using a given clientId.
void	updateClient(java.lang.String clientId, java.lang.Object data, CompletionListener listener)	Updates the data payload for a presence member using a given clientId.
void	updatePresence(PresenceMessage msg, CompletionListener listener)	Update the presence for this channel with a given PresenceMessage update.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GET_WAITFORSYNC

public static final java.lang.String GET_WAITFORSYNC

String parameter names for get() call with Param... as an argument

See Also:

Constant Field Values

GET_CLIENTID

public static final java.lang.String GET_CLIENTID

See Also:

Constant Field Values

GET_CONNECTIONID

public static final java.lang.String GET_CONNECTIONID

See Also:

Constant Field Values

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 Detail

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(java.lang.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(java.util.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(java.util.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(java.util.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(java.lang.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(java.lang.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(java.lang.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(java.lang.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(java.lang.String clientId,
                        java.lang.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(java.lang.String clientId,
                        java.lang.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(java.lang.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(java.lang.String clientId,
                         java.lang.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(java.lang.String clientId,
                         java.lang.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(java.lang.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(java.lang.String clientId,
                        java.lang.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(java.lang.String clientId,
                        java.lang.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