io.ably.lib.rest

Class AblyBase

java.lang.Object

io.ably.lib.rest.AblyBase

All Implemented Interfaces:

java.lang.AutoCloseable

Direct Known Subclasses:

AblyRest

public abstract class AblyBase
extends java.lang.Object
implements java.lang.AutoCloseable

A client that offers a simple stateless API to interact directly with Ably's REST API. This class implements AutoCloseable so you can use it in try-with-resources constructs and have the JDK close it for you.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	AblyBase.Channels A collection of Channels associated with an Ably instance.

Field Summary

Fields

Modifier and Type	Field and Description
Auth	auth An Auth object.
AblyBase.Channels	channels An AblyBase.Channels object.
Http	http
HttpCore	httpCore
ClientOptions	options
Platform	platform
protected PlatformAgentProvider	platformAgentProvider
Push	push An Push object.

Constructor Summary

Constructors

Constructor and Description
AblyBase(ClientOptions options, PlatformAgentProvider platformAgentProvider) Construct a client object using an Ably ClientOptions object.
AblyBase(java.lang.String key, PlatformAgentProvider platformAgentProvider) Constructs a client object using an Ably API key or token string.

Method Summary

Modifier and Type	Method and Description
void	close() Causes the connection to close, entering the [ConnectionState.closing state.
protected void	onAuthError(ErrorInfo errorInfo) Authentication error occurred
protected void	onAuthUpdated(java.lang.String token, boolean waitForResponse) Override this method in AblyRealtime and pass updated token to ConnectionManager
protected void	onAuthUpdatedAsync(java.lang.String token, Auth.AuthUpdateResult authUpdateResult) Override this method in AblyRealtime and pass updated token to ConnectionManager
protected void	onClientIdSet(java.lang.String clientId) clientId set by late initialisation
PublishResponse[]	publishBatch(Message.Batch[] pubSpecs, ChannelOptions channelOptions) Publish an array of Message.Batch objects to one or more channels, up to a maximum of 100 channels.
PublishResponse[]	publishBatch(Message.Batch[] pubSpecs, ChannelOptions channelOptions, Param[] params) Publish an array of Message.Batch objects to one or more channels, up to a maximum of 100 channels.
void	publishBatchAsync(Message.Batch[] pubSpecs, ChannelOptions channelOptions, Callback<PublishResponse[]> callback) Asynchronously publish an array of Message.Batch objects to one or more channels, up to a maximum of 100 channels.
void	publishBatchAsync(Message.Batch[] pubSpecs, ChannelOptions channelOptions, Param[] params, Callback<PublishResponse[]> callback) Asynchronously publish an array of Message.Batch objects to one or more channels, up to a maximum of 100 channels.
HttpPaginatedResponse	request(java.lang.String method, java.lang.String path, Param[] params, HttpCore.RequestBody body, Param[] headers) Makes a REST request to a provided path.
void	requestAsync(java.lang.String method, java.lang.String path, Param[] params, HttpCore.RequestBody body, Param[] headers, AsyncHttpPaginatedResponse.Callback callback) Makes a async REST request to a provided path.
PaginatedResult<Stats>	stats(Param[] params) Queries the REST /stats API and retrieves your application's usage statistics.
void	statsAsync(Param[] params, Callback<AsyncPaginatedResult<Stats>> callback) Asynchronously queries the REST /stats API and retrieves your application's usage statistics.
long	time() Retrieves the time from the Ably service as milliseconds since the Unix epoch.
void	timeAsync(Callback<java.lang.Long> callback) Asynchronously retrieves the time from the Ably service as milliseconds since the Unix epoch.

Methods inherited from class java.lang.Object

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

Field Detail

options

public final ClientOptions options

http

public final Http http

httpCore

public final HttpCore httpCore

auth

public final Auth auth

An Auth object.

Spec: RSC5

channels

public final AblyBase.Channels channels

An AblyBase.Channels object.

Spec: RSN1

platform

public final Platform platform

push

public final Push push

An Push object.

Spec: RSH7

platformAgentProvider

protected final PlatformAgentProvider platformAgentProvider

Constructor Detail

AblyBase

public AblyBase(java.lang.String key,
                PlatformAgentProvider platformAgentProvider)
         throws AblyException

Constructs a client object using an Ably API key or token string.

Spec: RSC1

Parameters:

key - The Ably API key or token string used to validate the client.

platformAgentProvider - provides platform agent for the agent header.

Throws:

AblyException

AblyBase

public AblyBase(ClientOptions options,
                PlatformAgentProvider platformAgentProvider)
         throws AblyException

Construct a client object using an Ably ClientOptions object.

Spec: RSC1

Parameters:

options - A ClientOptions object to configure the client connection to Ably.

platformAgentProvider - provides platform agent for the agent header.

Throws:

AblyException

Method Detail

close

public void close()
           throws java.lang.Exception

Causes the connection to close, entering the [ConnectionState.closing state. Once closed, the library does not attempt to re-establish the connection without an explicit call to Connection.connect().

Spec: RTN12

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.lang.Exception

time

public long time()
          throws AblyException

Retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably Auth.TokenRequest with a more accurate timestamp should use the Auth.AuthOptions.queryTime property instead of this method.

Spec: RSC16

Returns:

The time as milliseconds since the Unix epoch.

Throws:

AblyException

timeAsync

public void timeAsync(Callback<java.lang.Long> callback)

Asynchronously retrieves the time from the Ably service as milliseconds since the Unix epoch. Clients that do not have access to a sufficiently well maintained time source and wish to issue Ably Auth.TokenRequest with a more accurate timestamp should use the Auth.AuthOptions.queryTime property instead of this method.

Spec: RSC16

Parameters:

callback - Listener with the time as milliseconds since the Unix epoch.

This callback is invoked on a background thread

stats

public PaginatedResult<Stats> stats(Param[] params)
                             throws AblyException

Queries the REST /stats API and retrieves your application's usage statistics.

Parameters:

params - query options:

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

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

direction (RSC6b2) - The order for which stats are returned in. Valid values are backwards which orders stats from most recent to oldest, or forwards which orders stats from oldest to most recent. The default is backwards.

limit (RSC6b3) - An upper limit on the number of stats returned. The default is 100, and the maximum is 1000.

unit (RSC6b4) - minute, hour, day or month. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query.)

Spec: RSC6a

Returns:

A PaginatedResult object containing an array of Stats objects.

Throws:

AblyException

statsAsync

public void statsAsync(Param[] params,
                       Callback<AsyncPaginatedResult<Stats>> callback)

Asynchronously queries the REST /stats API and retrieves your application's usage statistics.

Parameters:

params - query options:

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

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

direction (RSC6b2) - The order for which stats are returned in. Valid values are backwards which orders stats from most recent to oldest, or forwards which orders stats from oldest to most recent. The default is backwards.

limit (RSC6b3) - An upper limit on the number of stats returned. The default is 100, and the maximum is 1000.

unit (RSC6b4) - minute, hour, day or month. Based on the unit selected, the given start or end times are rounded down to the start of the relevant interval depending on the unit granularity of the query.)

Spec: RSC6a

callback - Listener which returns a AsyncPaginatedResult object containing an array of Stats objects.

This callback is invoked on a background thread

request

public HttpPaginatedResponse request(java.lang.String method,
                                     java.lang.String path,
                                     Param[] params,
                                     HttpCore.RequestBody body,
                                     Param[] headers)
                              throws AblyException

Makes a REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support.

Spec: RSC19

Parameters:

method - The request method to use, such as GET, POST.

path - The request path.

params - The parameters to include in the URL query of the request. The parameters depend on the endpoint being queried. See the REST API reference for the available parameters of each endpoint.

body - The RequestBody of the request.

headers - Additional HTTP headers to include in the request.

Returns:

An HttpPaginatedResponse object returned by the HTTP request, containing an empty or JSON-encodable object.

Throws:

AblyException - if it was not possible to complete the request, or an error response was received

requestAsync

public void requestAsync(java.lang.String method,
                         java.lang.String path,
                         Param[] params,
                         HttpCore.RequestBody body,
                         Param[] headers,
                         AsyncHttpPaginatedResponse.Callback callback)

Makes a async REST request to a provided path. This is provided as a convenience for developers who wish to use REST API functionality that is either not documented or is not yet included in the public API, without having to directly handle features such as authentication, paging, fallback hosts, MsgPack and JSON support.

Spec: RSC19

Parameters:

method - The request method to use, such as GET, POST.

path - The request path.

params - The parameters to include in the URL query of the request. The parameters depend on the endpoint being queried. See the REST API reference for the available parameters of each endpoint.

body - The RequestBody of the request.

headers - Additional HTTP headers to include in the request.

callback - called with the asynchronous result, returns an AsyncHttpPaginatedResponse object returned by the HTTP request, containing an empty or JSON-encodable object.

This callback is invoked on a background thread

publishBatch

@Experimental
public PublishResponse[] publishBatch(Message.Batch[] pubSpecs,
                                                    ChannelOptions channelOptions)
                                             throws AblyException

Publish an array of Message.Batch objects to one or more channels, up to a maximum of 100 channels. Each Message.Batch object can contain a single message or an array of messages. Returns an array of PublishResponse object.

Spec: BO2a

Parameters:

pubSpecs - An array of Message.Batch objects.

channelOptions - A ClientOptions object to configure the client connection to Ably.

Returns:

A PublishResponse object.

Throws:

AblyException

publishBatch

@Experimental
public PublishResponse[] publishBatch(Message.Batch[] pubSpecs,
                                                    ChannelOptions channelOptions,
                                                    Param[] params)
                                             throws AblyException

Publish an array of Message.Batch objects to one or more channels, up to a maximum of 100 channels. Each Message.Batch object can contain a single message or an array of messages. Returns an array of PublishResponse object.

Spec: BO2a

Parameters:

pubSpecs - An array of Message.Batch objects.

channelOptions - A ClientOptions object to configure the client connection to Ably.

params - params to pass into the initial query

Returns:

A PublishResponse object.

Throws:

AblyException

publishBatchAsync

@Experimental
public void publishBatchAsync(Message.Batch[] pubSpecs,
                                            ChannelOptions channelOptions,
                                            Callback<PublishResponse[]> callback)
                                     throws AblyException

Asynchronously publish an array of Message.Batch objects to one or more channels, up to a maximum of 100 channels. Each Message.Batch object can contain a single message or an array of messages. Returns an array of PublishResponse object.

Spec: BO2a

Parameters:

pubSpecs - An array of Message.Batch objects.

channelOptions - A ClientOptions object to configure the client connection to Ably.

callback - callback A callback with PublishResponse object.

This callback is invoked on a background thread

Throws:

AblyException

publishBatchAsync

@Experimental
public void publishBatchAsync(Message.Batch[] pubSpecs,
                                            ChannelOptions channelOptions,
                                            Param[] params,
                                            Callback<PublishResponse[]> callback)
                                     throws AblyException

Asynchronously publish an array of Message.Batch objects to one or more channels, up to a maximum of 100 channels. Each Message.Batch object can contain a single message or an array of messages. Returns an array of PublishResponse object.

Spec: BO2a

Parameters:

pubSpecs - An array of Message.Batch objects.

channelOptions - A ClientOptions object to configure the client connection to Ably.

params - params to pass into the initial query

callback - A callback with PublishResponse object.

This callback is invoked on a background thread

Throws:

AblyException

onAuthUpdated

protected void onAuthUpdated(java.lang.String token,
                             boolean waitForResponse)
                      throws AblyException

Override this method in AblyRealtime and pass updated token to ConnectionManager

Parameters:

token - new token

waitForResponse - wait for server response before returning from method

Throws:

AblyException

onAuthUpdatedAsync

protected void onAuthUpdatedAsync(java.lang.String token,
                                  Auth.AuthUpdateResult authUpdateResult)

Override this method in AblyRealtime and pass updated token to ConnectionManager

Parameters:

token - new token

authUpdateResult - Callback result

onAuthError

protected void onAuthError(ErrorInfo errorInfo)

Authentication error occurred

onClientIdSet

protected void onClientIdSet(java.lang.String clientId)

clientId set by late initialisation