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 Summary

    Fields 
    Modifier and Type Field Description
    boolean addRequestIds
    When true, every REST request to Ably should include a random string in the request_id query string parameter.
    java.util.Map<java.lang.String,​java.lang.String> agents
    A set of additional entries for the Ably agent header.
    int asyncHttpThreadpoolSize
    Allows the caller to specify a non-default size for the asyncHttp threadpool
    boolean autoConnect
    When true, the client connects to Ably as soon as it is instantiated.
    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.
    java.lang.String clientId
    A client ID, used for identifying this client when publishing messages or for presence purposes.
    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.
    boolean echoMessages
    If false, prevents messages originating from this connection being echoed back on the same connection.
    java.lang.String environment
    Enables a custom environment to be used with the Ably service.
    java.lang.String[] fallbackHosts
    An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host.
    boolean fallbackHostsUseDefault
    Deprecated.
    long fallbackRetryTimeout
    The maximum time before HTTP requests are retried against the default endpoint.
    java.util.Map<java.lang.String,​java.lang.String> headers
    FIXME: unused
    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.
    int httpOpenTimeout
    Timeout for opening a connection to Ably to initiate an HTTP request.
    int httpRequestTimeout
    Timeout for a client performing a complete HTTP request to Ably, including the connection phase.
    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.
    Storage localStorage
    Custom Local Device storage.
    Log.LogHandler logHandler
    Controls the log output of the library.
    int logLevel
    Controls the verbosity of the logs output from the library.
    int port
    Enables a non-default Ably port to be specified.
    ProxyOptions proxy
    Proxy settings
    boolean pushFullWait
    Whether to tell Ably to wait for push REST requests to fully wait for all their effects before responding.
    boolean queueMessages
    If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states.
    java.lang.String realtimeHost
    Enables a non-default Ably host to be specified for realtime connections.
    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.
    java.lang.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.
    java.lang.String restHost
    Enables a non-default Ably host to be specified.
    boolean tls
    When false, the client will use an insecure connection.
    int tlsPort
    Enables a non-default Ably TLS port to be specified.
    Param[] transportParams
    A set of key-value pairs that can be used to pass in arbitrary connection parameters, such as heartbeatInterval or remainPresentFor.
    boolean useBinaryProtocol
    When true, the more efficient MsgPack binary encoding is used.

    Fields inherited from class io.ably.lib.rest.Auth.AuthOptions

    authCallback, authHeaders, authMethod, authParams, authUrl, key, queryTime, token, tokenDetails, useTokenAuth

  • Constructor Summary

    Constructors 
    Constructor Description
    ClientOptions()
    Creates a ClientOptions instance used to configure Rest and Realtime clients
    ClientOptions​(java.lang.String key)
    Creates a ClientOptions instance used to configure Rest and Realtime clients

  • Method Summary

    Methods inherited from class java.lang.Object

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

  • Field Details

    • clientId

      public java.lang.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 java.util.Map<java.lang.String,​java.lang.String> headers
      FIXME: unused

    • restHost

      public java.lang.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 java.lang.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 java.lang.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

    • proxy

      public ProxyOptions proxy
      Proxy settings

    • environment

      public java.lang.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

    • 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

    • fallbackHosts

      public java.lang.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

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