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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ChannelBase.MessageListener	An interface whereby a client maybe notified of message on a channel.

Nested classes/interfaces inherited from class io.ably.lib.util.EventEmitter

EventEmitter.Filter

Field Summary

Fields

Modifier and Type	Field	Description
java.lang.String	name	The channel name.
Presence	presence	A Presence object.
ChannelProperties	properties	A ChannelProperties object.
ErrorInfo	reason	An ErrorInfo object describing the last error which occurred on the channel, if any.
ChannelState	state	The current ChannelState of the channel.

Method Summary

Modifier and Type	Method	Description
protected void	apply(ChannelStateListener listener, ChannelEvent event, java.lang.Object... args)
void	attach()	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).
void	attach(CompletionListener listener)	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).
void	detach()	Detach from this channel.
void	detach(CompletionListener listener)	Detach from this channel.
void	emit(ChannelState state, ChannelStateListener.ChannelStateChange channelStateChange)
ChannelMode[]	getModes()
java.util.Map<java.lang.String,java.lang.String>	getParams()
PaginatedResult<Message>	history(Param[] params)	Retrieves a PaginatedResult object, containing an array of historical Message objects for the channel.
void	historyAsync(Param[] params, Callback<AsyncPaginatedResult<Message>> callback)	Asynchronously retrieves a PaginatedResult object, containing an array of historical Message objects for the channel.
void	on(ChannelState state, ChannelStateListener listener)
void	once(ChannelState state, ChannelStateListener listener)
void	publish(Message message)	Publishes a message to the channel.
void	publish(Message[] messages)	Publishes an array of messages to the channel.
void	publish(Message[] messages, CompletionListener listener)	Publishes an array of messages to the channel.
void	publish(Message message, CompletionListener listener)	Publishes a message to the channel.
void	publish(java.lang.String name, java.lang.Object data)	Publishes a single message to the channel with the given event name and payload.
void	publish(java.lang.String name, java.lang.Object data, CompletionListener listener)	Publishes a single message to the channel with the given event name and payload.
void	setConnected(boolean reattachOnResumeFailure)
void	setConnectionClosed(ErrorInfo reason)	(RTL3b) If the connection state enters the CLOSED state, then an ATTACHING or ATTACHED channel state will transition to DETACHED.
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
void	setOptions(ChannelOptions options)	Sets the ChannelOptions for the channel.
void	setOptions(ChannelOptions options, CompletionListener listener)	Sets the ChannelOptions for the channel.
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.
void	subscribe(ChannelBase.MessageListener listener)	Registers a listener for messages on this channel.
void	subscribe(java.lang.String[] names, ChannelBase.MessageListener listener)	Registers a listener for messages on this channel for multiple event name values.
void	subscribe(java.lang.String name, ChannelBase.MessageListener listener)	Registers a listener for messages with a given event name on this channel.
void	sync()
void	unsubscribe()	Deregisters all listeners to messages on this channel.
void	unsubscribe(ChannelBase.MessageListener listener)	Deregisters the given listener (for any/all event names).
void	unsubscribe(java.lang.String[] names, ChannelBase.MessageListener listener)	Deregisters the given listener from all event names in the array.
void	unsubscribe(java.lang.String name, ChannelBase.MessageListener listener)	Deregisters the given listener for the specified event name.

Methods inherited from class io.ably.lib.util.EventEmitter

emit, off, off, off, on, on, once, once

Methods inherited from class java.lang.Object

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

Field Detail

name

public final java.lang.String name

The channel name.

presence

public final Presence presence

A Presence object.

Spec: RTL9

state

public ChannelState state

The current ChannelState of the channel.

Spec: RTL2b

reason

public ErrorInfo reason

An ErrorInfo object describing the last error which occurred on the channel, if any.

Spec: RTL4e

properties

public ChannelProperties properties

A ChannelProperties object.

Spec: CP1, RTL15

Method Detail

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

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

public void sync()
          throws AblyException

Throws:

AblyException

setConnected

public void setConnected(boolean reattachOnResumeFailure)

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).

apply

protected void apply(ChannelStateListener listener,
                     ChannelEvent event,
                     java.lang.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

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

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 java.util.Map<java.lang.String,java.lang.String> getParams()

getModes

public ChannelMode[] getModes()

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)