Package io.ably.lib.realtime

Class Presence

java.lang.Object

io.ably.lib.realtime.Presence

public class Presence
extends java.lang.Object

A class that provides access to presence operations and state for the associated 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 presence messages

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	(RTP13) Presence#syncComplete returns true if the initial SYNC operation has completed for the members present on the channel

Method Summary

Modifier and Type	Method	Description
void	enter(java.lang.Object data, CompletionListener listener)	Enter this client into this channel.
void	enterClient(java.lang.String clientId)	Enter a specified client into this channel.
void	enterClient(java.lang.String clientId, java.lang.Object data)	Enter a specified client into this channel.
void	enterClient(java.lang.String clientId, java.lang.Object data, CompletionListener listener)	Enter a specified client into this channel.
PresenceMessage[]	get(boolean wait)	Get the presence state for this Channel, optionally waiting for sync to complete.
PresenceMessage[]	get(Param... params)	Get the presence state for this channel.
PresenceMessage[]	get(java.lang.String clientId, boolean wait)	Get the presence state for a given clientId.
PaginatedResult<PresenceMessage>	history(Param[] params)	Obtain recent history for this channel using the REST API.
void	historyAsync(Param[] params, Callback<AsyncPaginatedResult<PresenceMessage>> callback)
void	leave(CompletionListener listener)	Leave this client from this channel.
void	leave(java.lang.Object data, CompletionListener listener)	Leave this client from this channel.
void	leaveClient(java.lang.String clientId)	Leave a given client from this channel.
void	leaveClient(java.lang.String clientId, java.lang.Object data)	Leave a given client from this channel.
void	leaveClient(java.lang.String clientId, java.lang.Object data, CompletionListener listener)	Leave a given client from this channel.
void	subscribe(Presence.PresenceListener listener)	Same as above without completion listener
void	subscribe(Presence.PresenceListener listener, CompletionListener completionListener)	Subscribe to presence events on the associated Channel.
void	subscribe(PresenceMessage.Action action, Presence.PresenceListener listener)	Same as above without completion listener
void	subscribe(PresenceMessage.Action action, Presence.PresenceListener listener, CompletionListener completionListener)	Subscribe to presence events with a specific action on the associated Channel.
void	subscribe(java.util.EnumSet<PresenceMessage.Action> actions, Presence.PresenceListener listener)	Same as above without completion listener
void	subscribe(java.util.EnumSet<PresenceMessage.Action> actions, Presence.PresenceListener listener, CompletionListener completionListener)	Subscribe to presence events with specific actions on the associated Channel.
void	unsubscribe()	Unsubscribe all subscribed presence lisceners for this channel.
void	unsubscribe(Presence.PresenceListener listener)	Unsubscribe a previously subscribed presence listener for this channel.
void	unsubscribe(PresenceMessage.Action action, Presence.PresenceListener listener)	Unsubscribe a previously subscribed presence listener for this channel from specific action.
void	unsubscribe(java.util.EnumSet<PresenceMessage.Action> actions, Presence.PresenceListener listener)	Unsubscribe a previously subscribed presence listener for this channel from specific actions.
void	update(java.lang.Object data, CompletionListener listener)	Update the presence data for this client.
void	updateClient(java.lang.String clientId)	Update the presence data for a specified client into this channel.
void	updateClient(java.lang.String clientId, java.lang.Object data)	Update the presence data for a specified client into this channel.
void	updateClient(java.lang.String clientId, java.lang.Object data, CompletionListener listener)	Update the presence data for a specified client into this channel.
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

(RTP13) Presence#syncComplete returns true if the initial SYNC operation has completed for the members present on the channel

Method Detail

get

public PresenceMessage[] get(Param... params)
                      throws AblyException

Get the presence state for this channel. Take Param[] array as an argument. Implicitly attaches the channel. However, if the channel is in or moves to the FAILED state before the operation succeeds, it will result in an error

Parameters:

params -

Returns:

Throws:

AblyException

java.lang.InterruptedException

get

public PresenceMessage[] get(boolean wait)
                      throws AblyException

Get the presence state for this Channel, optionally waiting for sync to complete. Implicitly attaches the Channel. However, if the channel is in or moves to the FAILED state before the operation succeeds, it will result in an error

Throws:

AblyException

get

public PresenceMessage[] get(java.lang.String clientId,
                             boolean wait)
                      throws AblyException

Get the presence state for a given clientId. Implicitly attaches the Channel. However, if the channel is in or moves to the FAILED state before the operation succeeds, it will result in an error

Parameters:

wait -

Returns:

Throws:

java.lang.InterruptedException

AblyException

subscribe

public void subscribe(Presence.PresenceListener listener,
                      CompletionListener completionListener)
               throws AblyException

Subscribe to presence events on the associated Channel. This implicitly attaches the Channel if it is not already attached.

Parameters:

listener - : the listener to me notified on arrival of presence messages.

completionListener - listener to be called on success/failure

Throws:

AblyException

subscribe

public void subscribe(Presence.PresenceListener listener)
               throws AblyException

Same as above without completion listener

Throws:

AblyException

unsubscribe

public void unsubscribe(Presence.PresenceListener listener)

Unsubscribe a previously subscribed presence listener for this channel.

Parameters:

listener - : the previously subscribed listener.

subscribe

public void subscribe(PresenceMessage.Action action,
                      Presence.PresenceListener listener,
                      CompletionListener completionListener)
               throws AblyException

Subscribe to presence events with a specific action on the associated Channel. This implicitly attaches the Channel if it is not already attached.

Parameters:

action - to be observed

listener -

completionListener - listener to be called on success/failure

Throws:

AblyException

subscribe

public void subscribe(PresenceMessage.Action action,
                      Presence.PresenceListener listener)
               throws AblyException

Same as above without completion listener

Throws:

AblyException

unsubscribe

public void unsubscribe(PresenceMessage.Action action,
                        Presence.PresenceListener listener)

Unsubscribe a previously subscribed presence listener for this channel from specific action.

Parameters:

action -

listener -

subscribe

public void subscribe(java.util.EnumSet<PresenceMessage.Action> actions,
                      Presence.PresenceListener listener,
                      CompletionListener completionListener)
               throws AblyException

Subscribe to presence events with specific actions on the associated Channel. This implicitly attaches the Channel if it is not already attached.

Parameters:

actions - to be observed

listener -

completionListener - listener to be called on success/failure

Throws:

AblyException

subscribe

public void subscribe(java.util.EnumSet<PresenceMessage.Action> actions,
                      Presence.PresenceListener listener)
               throws AblyException

Same as above without completion listener

Throws:

AblyException

unsubscribe

public void unsubscribe(java.util.EnumSet<PresenceMessage.Action> actions,
                        Presence.PresenceListener listener)

Unsubscribe a previously subscribed presence listener for this channel from specific actions.

Parameters:

actions -

listener -

unsubscribe

public void unsubscribe()

Unsubscribe all subscribed presence lisceners for this channel.

enter

public void enter(java.lang.Object data,
                  CompletionListener listener)
           throws AblyException

Enter this client into this channel. This client will be added to the presence set and presence subscribers will see an enter message for this client.

Parameters:

data - : optional data (eg a status message) for this member. See io.ably.types.Data for the supported data types.

listener - : a listener to be notified on completion of the operation.

Throws:

AblyException

update

public void update(java.lang.Object data,
                   CompletionListener listener)
            throws AblyException

Update the presence data for this client. If the client is not already a member of the presence set it will be added, and presence subscribers will see an enter or update message for this client.

Parameters:

data - : optional data (eg a status message) for this member. See io.ably.types.Data for the supported data types.

listener - : a listener to be notified on completion of the operation.

Throws:

AblyException

leave

public void leave(java.lang.Object data,
                  CompletionListener listener)
           throws AblyException

Leave this client from this channel. This client will be removed from the presence set and presence subscribers will see a leave message for this client.

Parameters:

data - : optional data (eg a status message) for this member. See io.ably.types.Data for the supported data types.

listener - : a listener to be notified on completion of the operation.

Throws:

AblyException

leave

public void leave(CompletionListener listener)
           throws AblyException

Leave this client from this channel. This client will be removed from the presence set and presence subscribers will see a leave message for this client.

Parameters:

listener - : a listener to be notified on completion of the operation.

Throws:

AblyException

enterClient

public void enterClient(java.lang.String clientId)
                 throws AblyException

Enter a specified client into this channel. The given clientId will be added to the presence set and presence subscribers will see a corresponding presence message with an empty data payload. This method is provided to support connections (eg connections from application server instances) that act on behalf of multiple clientIds. In order to be able to enter the channel with this method, the client library must have been instanced either with a key, or with a token bound to the wildcard clientId.

Parameters:

clientId - : the id of the client.

Throws:

AblyException

enterClient

public void enterClient(java.lang.String clientId,
                        java.lang.Object data)
                 throws AblyException

Enter a specified client into this channel. The given client will be added to the presence set and presence subscribers will see a corresponding presence message. This method is provided to support connections (eg connections from application server instances) that act on behalf of multiple clientIds. In order to be able to enter the channel with this method, the client library must have been instanced either with a key, or with a token bound to the wildcard clientId.

Parameters:

clientId - : the id of the client.

data - : optional data (eg a status message) for this member.

Throws:

AblyException

enterClient

public void enterClient(java.lang.String clientId,
                        java.lang.Object data,
                        CompletionListener listener)
                 throws AblyException

Enter a specified client into this channel. The given client will be added to the presence set and presence subscribers will see a corresponding presence message. This method is provided to support connections (eg connections from application server instances) that act on behalf of multiple clientIds. In order to be able to enter the channel with this method, the client library must have been instanced either with a key, or with a token bound to the wildcard clientId.

Parameters:

clientId - : the id of the client.

data - : optional data (eg a status message) for this member.

listener - : a listener to be notified on completion of the operation.

Throws:

AblyException

updateClient

public void updateClient(java.lang.String clientId)
                  throws AblyException

Update the presence data for a specified client into this channel. If the client is not already a member of the presence set it will be added, and presence subscribers will see a corresponding presence message with an empty data payload. As for #enterClient above, the connection must be authenticated in a way that enables it to represent an arbitrary clientId.

Parameters:

clientId - : the id of the client.

Throws:

AblyException

updateClient

public void updateClient(java.lang.String clientId,
                         java.lang.Object data)
                  throws AblyException

Update the presence data for a specified client into this channel. If the client is not already a member of the presence set it will be added, and presence subscribers will see an enter or update message for this client. As for #enterClient above, the connection must be authenticated in a way that enables it to represent an arbitrary clientId.

Parameters:

clientId - : the id of the client.

data - : optional data (eg a status message) for this member.

Throws:

AblyException

updateClient

public void updateClient(java.lang.String clientId,
                         java.lang.Object data,
                         CompletionListener listener)
                  throws AblyException

Update the presence data for a specified client into this channel. If the client is not already a member of the presence set it will be added, and presence subscribers will see an enter or update message for this client. As for #enterClient above, the connection must be authenticated in a way that enables it to represent an arbitrary clientId.

Parameters:

clientId - : the id of the client.

data - : optional data (eg a status message) for this member.

listener - : a listener to be notified on completion of the operation.

Throws:

AblyException

leaveClient

public void leaveClient(java.lang.String clientId)
                 throws AblyException

Leave a given client from this channel. This client will be removed from the presence set and presence subscribers will see a corresponding presence message with an empty data payload.

Parameters:

clientId - : the id of the client.

Throws:

AblyException

leaveClient

public void leaveClient(java.lang.String clientId,
                        java.lang.Object data)
                 throws AblyException

Leave a given client from this channel. This client will be removed from the presence set and presence subscribers will see a leave message for this client.

Parameters:

clientId - : the id of the client.

data - : optional data (eg a status message) for this member.

Throws:

AblyException

leaveClient

public void leaveClient(java.lang.String clientId,
                        java.lang.Object data,
                        CompletionListener listener)
                 throws AblyException

Leave a given client from this channel. This client will be removed from the presence set and presence subscribers will see a leave message for this client.

Parameters:

clientId - : the id of the client.

data - : optional data (eg a status message) for this member.

listener - : a listener to be notified on completion of the operation.

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.

Throws:

AblyException

history

public PaginatedResult<PresenceMessage> history(Param[] params)
                                         throws AblyException

Obtain recent history for this channel using the REST API. The history provided relates to all clients of this application, not just this instance.

Parameters:

params - : the request params. See the Ably REST API documentation for more details.

Throws:

AblyException

historyAsync

public void historyAsync(Param[] params,
                         Callback<AsyncPaginatedResult<PresenceMessage>> callback)