Channels
Channels
The Channels object, accessed from the rest library client constructor, is used to create and destroy Channel objects. It exposes the following public methods:
Channels Methods
get
Channel get(String channelName, ChannelOptions channelOptions)
Creates a new Channel object if none for the channel exists, or returns the existing channel object.
release
release(String channelName)
Releases all SDK-held references to a Channel object, enabling it to be garbage collected. It can be useful for applications that work with a continually changing set of channels on a single client and need to avoid unbounded memory growth; if this does not describe your application, don't call it.
This method only affects the local client-side representation of the channel. The channel itself on the Ably platform is not deleted or changed, and other client instances (in the same or different processes) are unaffected.
After release, calling channels.get(channelName) returns a fresh channel object.
Channel
The Channel object, created via the Channels object, is used to interact with a specific channel.
Ably::Rest::Channel Attributes
The Channel object exposes the following public attributes:
name
The name String unique to this channel.
presence
Provides access to the REST Presence object for this channel which can be used to get members present on the channel, or retrieve presence event history.
push
Provides access to the PushChannel object for this channel which can be used to access members present on the channel, or participate in presence.
Channel Methods
publish
There are two overloaded versions of this method:
publish(String name, Object data)
Publish a single message on this channel based on a given event name and payload. A callback may optionally be passed in to this call to be notified of success of the operation.
It is also possible to publish a message to multiple channels at once using our batch publish feature.
publish(Message[] messages)
Publish several messages on this channel. A callback may optionally be passed in to this call to be notified of success of the operation.
The entire messages array is published atomically. This means that:
- Either they will all be successfully published or none of them will
- The max message size limit applies to the total size of all messages in the array
- The publish will only count as a single message for the purpose of per-channel rate limit
- If you are using client-specified message IDs for publish idempotency, they must conform to certain restrictions
Parameters
| Parameter | Description | Type |
|---|---|---|
| data | Data payload for the message. The supported payload types are Strings, Hash or Array objects that can be serialized to JSON using to_json, binary data as ASCII-8BIT byte arrays, and null. (Note that if sending a byte array, it should be the entire payload; a hash or array with a bytearray field within it may not be correctly encoded) | Object |
| messages | An array of message objects to publish | Message [] |
Failure
On failure to publish the message, an AblyException will be raised.
history
PaginatedResult<Message> history(Hash options)
Gets a paginated set of historical messages for this channel. If the channel is configured to persist messages to disk, then message history will typically be available for 24 - 72 hours. If not, messages are only retained in memory by the Ably service for two minutes.
Parameters
| Parameter | Description | Type |
|---|---|---|
| params | An optional set of key value pairs containing the query parameters, as specified in the message history API documentation | Object |
Returns
On success, the returned PaginatedResult encapsulates an array of Message objects corresponding to the current page of results. PaginatedResult supports pagination using next and first methods.
Failure to retrieve the message history will raise an AblyException
Related types
Ably::Models::Message
A Message represents an individual message that is sent to or received from Ably.
name
The event name, if provided.
Type: String
data
The message payload, if provided.
Type: String, Binary (ASCII-8BIT String), Hash, Array
extras
Metadata and/or ancillary payloads, if provided. Valid payloads include push, headers (a map of strings to strings for arbitrary customer-supplied metadata), ephemeral, and privileged objects.
Type: Hash, Array
id
A Unique ID assigned by Ably to this message.
Type: String
client_id
The client ID of the publisher of this message.
Type: String
connection_id
The connection ID of the publisher of this message.
Type: String
connection_key
A connection key, which can optionally be included for a REST publish as part of the publishing on behalf of a realtime client functionality.
Type: String
timestamp
Timestamp when the message was first received by the Ably, as a Time object.
Type: Time
encoding
This will typically be empty as all messages received from Ably are automatically decoded client-side using this value. However, if the message encoding cannot be processed, this attribute will contain the remaining transformations not applied to the data payload.
Type: String
Message constructors
Message.fromEncoded
Message.fromEncoded(Object encodedMsg, ChannelOptions channelOptions?) -> Message
A static factory method to create a Message from a deserialized Message-like object encoded using Ably's wire protocol.
Parameters
| Parameter | Description | Type |
|---|---|---|
| encodedMsg | A Message-like deserialized object | Object |
| channelOptions | An optional ChannelOptions. If you have an encrypted channel, use this to allow the library to decrypt the data | Object |
Returns
A Message object
Message.fromEncodedArray
Message.fromEncodedArray(Object[] encodedMsgs, ChannelOptions channelOptions?) -> Message[]
A static factory method to create an array of Messages from an array of deserialized Message-like object encoded using Ably's wire protocol.
Parameters
| Parameter | Description | Type |
|---|---|---|
| encodedMsgs | An array of Message-like deserialized objects | Array |
| channelOptions | An optional ChannelOptions. If you have an encrypted channel, use this to allow the library to decrypt the data | Object |
Returns
An Array of Message objects
ChannelOptions Hash
Channel options are used for configuring encryption.
ChannelOptions, a Hash object, may optionally be specified when instancing a Channel, and this may be used to specify channel-specific options. The following key symbol values can be added to the Hash:
Attributes
| Parameter | Description | Type |
|---|---|---|
| :cipher | Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm, chaining mode, key length and key). See an example | CipherParams or an options hash containing at a minimum a key |
Ably::Models::PaginatedResult
A PaginatedResult is a type that represents a page of results for all message and presence history, stats and REST presence requests. The response from a Ably REST API paginated query is accompanied by metadata that indicates the relative queries available to the PaginatedResult object.
Attributes
| Property | Description | Type |
|---|---|---|
| items | contains the current page of results (for example an Array of Message or PresenceMessage objects for a channel history request) | Array <Message, Presence, Stats> |
Methods
first
PaginatedResult first
Returns a new PaginatedResult for the first page of results. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.
hasNexthas_next?
Boolean has_next?
Returns true if there are more pages available by calling next and returns false if this page is the last page available.
last?
Boolean last?
Returns true if this page is the last page and returns false if there are more pages available by calling next available.
next
PaginatedResult next
Returns a new PaginatedResult loaded with the next page of results. If there are no further pages, then is returned. When using the Realtime library, the first method returns a Deferrable and yields a PaginatedResult.
Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# When using the REST sync library
first_page = channel.history
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
next_page = first_page.next
puts "Page 1 item 1: #{next_page.items[1].data}"
puts "Last page?: #{next_page.is_last?}"
end
# When using the Realtime EventMachine library
channel.history do |first_page|
puts "Page 0 item 0: #{first_page.items[0].data}"
if first_page.has_next?
first_page.next do |next_page|
puts "Page 1 item 1: #{next_page.items[1].data}"
puts "Last page?: #{next_page.is_last?}"
end
end
end