ClientOptions (Ably documentation)

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 and 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`.
`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.
`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`	`httpMaxRetryDuration` Denotes elapsed time in which fallback host retries for HTTP requests will be attempted.
`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.
`long`	`suspendedRetryTimeout` This is a timeout when the connection enters the suspendedState.
`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 and 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 Detail
  - 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
  - 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 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
  - 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 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 Detail
  - 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

Class ClientOptions

Field Summary

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

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

clientId

logLevel

logHandler

tls

headers

restHost

realtimeHost

port

tlsPort

autoConnect

useBinaryProtocol

queueMessages

echoMessages

recover

proxy

environment

idempotentRestPublishing

httpOpenTimeout

httpRequestTimeout

httpMaxRetryDuration

httpMaxRetryCount

realtimeRequestTimeout

disconnectedRetryTimeout

fallbackHosts

suspendedRetryTimeout

fallbackHostsUseDefault

fallbackRetryTimeout

defaultTokenParams

channelRetryTimeout

transportParams

asyncHttpThreadpoolSize

pushFullWait

localStorage

addRequestIds

agents

Constructor Detail

ClientOptions

ClientOptions