Package io.ably.lib.rest

Class AblyBase

java.lang.Object
io.ably.lib.rest.AblyBase
All Implemented Interfaces:
AutoCloseable
Direct Known Subclasses:
AblyRest
public abstract class AblyBase extends Object implements 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.

  • Field Details

  • Constructor Details

    • AblyBase

      public AblyBase(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 Details

    • close

      public void close() throws 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 AutoCloseable
      Throws:
      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<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(String method, 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(String method, 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(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(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(String clientId)
      clientId set by late initialisation