Package io.ably.lib.types

Class ClientOptions

java.lang.Object
io.ably.lib.rest.Auth.AuthOptions
io.ably.lib.types.ClientOptions
Direct Known Subclasses:
DebugOptions
public class ClientOptions extends Auth.AuthOptions
Passes additional client-specific properties to the AblyRest or the AblyRealtime.

Extends an Auth.AuthOptions object.

Spec: TO3j

  • Field Details

    • clientId

      public String clientId
      A client ID, used for identifying this client when publishing messages or for presence purposes. The clientId can be any non-empty string, except it cannot contain a *. This option is primarily intended to be used in situations where the library is instantiated with a key. Note that a clientId may also be implicit in a token used to instantiate the library. An error will be raised if a clientId specified here conflicts with the clientId implicit in the token.

      Spec: RSC17, RSA4, RSA15, TO3a

    • logLevel

      public int logLevel
      Controls the verbosity of the logs output from the library. Levels include verbose, debug, info, warn and error.

      Spec: TO3b

    • logHandler

      public Log.LogHandler logHandler
      Controls the log output of the library. This is a function to handle each line of log output.

      Spec: TO3c

    • tls

      public boolean tls
      When false, the client will use an insecure connection. The default is true, meaning a TLS connection will be used to connect to Ably.

      Spec: RSC18, TO3d

    • headers

      public Map<String,String> headers
      FIXME: unused

    • restHost

      public String restHost
      Enables a non-default Ably host to be specified. For development environments only. The default value is rest.ably.io.

      Spec: RSC12, TO3k2

    • realtimeHost

      public String realtimeHost
      Enables a non-default Ably host to be specified for realtime connections. For development environments only. The default value is realtime.ably.io.

      Spec: RTC1d, TO3k3

    • port

      public int port
      Enables a non-default Ably port to be specified. For development environments only. The default value is 80.

      Spec: TO3k4

    • tlsPort

      public int tlsPort
      Enables a non-default Ably TLS port to be specified. For development environments only. The default value is 443.

      Spec: TO3k5

    • autoConnect

      public boolean autoConnect
      When true, the client connects to Ably as soon as it is instantiated. You can set this to false and explicitly connect to Ably using the Connection.connect() method. The default is true.

      Spec: RTC1b, TO3e

    • useBinaryProtocol

      public boolean useBinaryProtocol
      When true, the more efficient MsgPack binary encoding is used. When false, JSON text encoding is used. The default is true.

      Spec: TO3f

    • queueMessages

      public boolean queueMessages
      If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states. The default behavior enables applications to submit messages immediately upon instantiating the library without having to wait for the connection to be established. Applications may use this option to disable queueing if they wish to have application-level control over the queueing. The default is true.

      Spec: RTP16b, TO3g

    • echoMessages

      public boolean echoMessages
      If false, prevents messages originating from this connection being echoed back on the same connection. The default is true.

      Spec: RTC1a, TO3h

    • recover

      public String recover
      Enables a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library. This might typically be used by clients of the browser library to ensure connection state can be preserved when the user refreshes the page. A recovery key string can be explicitly provided, or alternatively if a callback function is provided, the client library will automatically persist the recovery key between page reloads and call the callback when the connection is recoverable. The callback is then responsible for confirming whether the connection should be recovered or not. See connection state recovery for further information.

      Spec: RTC1c, TO3i, RTN16i

    • proxy

      public ProxyOptions proxy
      Proxy settings

    • environment

      public String environment
      Enables a custom environment to be used with the Ably service.

      Spec: RSC15b, TO3k1

    • idempotentRestPublishing

      public boolean idempotentRestPublishing
      When true, enables idempotent publishing by assigning a unique message ID client-side, allowing the Ably servers to discard automatic publish retries following a failure such as a network fault. The default is true.

      Spec: RSL1k1, RTL6a1, TO3n

    • httpOpenTimeout

      public int httpOpenTimeout
      Timeout for opening a connection to Ably to initiate an HTTP request. The default is 4 seconds.

      Spec: TO3l3

    • httpRequestTimeout

      public int httpRequestTimeout
      Timeout for a client performing a complete HTTP request to Ably, including the connection phase. The default is 10 seconds.

      Spec: TO3l4

    • httpMaxRetryDuration

      public int httpMaxRetryDuration
      Denotes elapsed time in which fallback host retries for HTTP requests will be attempted. Default is 15 seconds. Spec: TO3l6

    • httpMaxRetryCount

      public int httpMaxRetryCount
      The maximum number of fallback hosts to use as a fallback when an HTTP request to the primary host is unreachable or indicates that it is unserviceable. The default value is 3.

      Spec: TO3l5

    • realtimeRequestTimeout

      public long realtimeRequestTimeout
      Timeout for the wait of acknowledgement for operations performed via a realtime connection, before the client library considers a request failed and triggers a failure condition. Operations include establishing a connection with Ably, or sending a HEARTBEAT, CONNECT, ATTACH, DETACH or CLOSE request. It is the equivalent of httpRequestTimeout but for realtime operations, rather than REST. The default is 10 seconds.

      Spec: TO3l11

    • disconnectedRetryTimeout

      public long disconnectedRetryTimeout
      When the connection enters the disconnected state, after this timeout, if the state is still disconnected, the client library will attempt to reconnect automatically. The default is 15 seconds (TO3l1).

      Spec: TO3l1

    • fallbackHosts

      public String[] fallbackHosts
      An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. If you have been provided a set of custom fallback hosts by Ably, please specify them here.

      Spec: RSC15b, RSC15a, TO3k6

    • suspendedRetryTimeout

      public long suspendedRetryTimeout
      This is a timeout when the connection enters the suspendedState. Client will try to connect indefinitely till state changes to connected. The default is 30 seconds.

      Spec: RTN14d, TO3l2

    • fallbackHostsUseDefault

      @Deprecated public boolean fallbackHostsUseDefault
      Deprecated.
      An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host. If you have been provided a set of custom fallback hosts by Ably, please specify them here.

      Spec: RSC15b, RSC15a, TO3k6

    • fallbackRetryTimeout

      public long fallbackRetryTimeout
      The maximum time before HTTP requests are retried against the default endpoint. The default is 600 seconds.

      Spec: TO3l10

    • defaultTokenParams

      public Auth.TokenParams defaultTokenParams
      When a Auth.TokenParams object is provided, it overrides the client library defaults when issuing new Ably Tokens or Ably Auth.TokenRequest.

      Spec: TO3j11

    • channelRetryTimeout

      public int channelRetryTimeout
      When a channel becomes ChannelState.suspended following a server initiated ChannelState.detached, after this delay, if the channel is still ChannelState.suspended and the connection is ConnectionState.connected, the client library will attempt to re-attach the channel automatically. The default is 15 seconds.

      Spec: RTL13b, TO3l7

    • transportParams

      public Param[] transportParams
      A set of key-value pairs that can be used to pass in arbitrary connection parameters, such as heartbeatInterval or remainPresentFor.

      Spec: RTC1f

    • asyncHttpThreadpoolSize

      public int asyncHttpThreadpoolSize
      Allows the caller to specify a non-default size for the asyncHttp threadpool

    • pushFullWait

      public boolean pushFullWait
      Whether to tell Ably to wait for push REST requests to fully wait for all their effects before responding.

    • localStorage

      public Storage localStorage
      Custom Local Device storage. In the case nothing is provided then a default implementation using SharedPreferences is used.

    • addRequestIds

      public boolean addRequestIds
      When true, every REST request to Ably should include a random string in the request_id query string parameter. The random string should be a url-safe base64-encoding sequence of at least 9 bytes, obtained from a source of randomness. This request ID must remain the same if a request is retried to a fallback host. Any log messages associated with the request should include the request ID. If the request fails, the request ID must be included in the ErrorInfo returned to the user. The default is false.

      Spec: TO3p

    • agents

      public Map<String,String> agents
      A set of additional entries for the Ably agent header. Each entry can be a key string or set of key-value pairs.

      Spec: RSC7d6

  • Constructor Details

    • ClientOptions

      public ClientOptions()
      Creates a ClientOptions instance used to configure Rest and Realtime clients

    • ClientOptions

      public ClientOptions(String key) throws AblyException
      Creates a ClientOptions instance used to configure Rest and Realtime clients
      Parameters:
      key - the key obtained from the application dashboard.
      Throws:
      AblyException - if the key is not in a valid format

  • Method Details

    • copy

      public ClientOptions copy()
      Internal method
      Returns:
      copy of client options

    • clearAuthOptions

      public void clearAuthOptions()
      Internal method

      clears all auth options