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
Passes additional client-specific properties to the
AblyRest
or the AblyRealtime
.
Extends an Auth.AuthOptions
object.
Spec: TO3j
-
Field Summary
FieldsModifier and TypeFieldDescriptionboolean
When true, every REST request to Ably should include a random string in the request_id query string parameter.A set of additional entries for the Ably agent header.int
Allows the caller to specify a non-default size for the asyncHttp threadpoolboolean
When true, the client connects to Ably as soon as it is instantiated.int
When a channel becomesChannelState.suspended
following a server initiatedChannelState.detached
, after this delay, if the channel is stillChannelState.suspended
and the connection isConnectionState.connected
, the client library will attempt to re-attach the channel automatically.A client ID, used for identifying this client when publishing messages or for presence purposes.When aAuth.TokenParams
object is provided, it overrides the client library defaults when issuing new Ably Tokens or AblyAuth.TokenRequest
.long
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
If false, prevents messages originating from this connection being echoed back on the same connection.Enables a custom environment to be used with the Ably service.String[]
An array of fallback hosts to be used in the case of an error necessitating the use of an alternative host.boolean
Deprecated.long
The maximum time before HTTP requests are retried against the default endpoint.FIXME: unusedint
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
Denotes elapsed time in which fallback host retries for HTTP requests will be attempted.int
Timeout for opening a connection to Ably to initiate an HTTP request.int
Timeout for a client performing a complete HTTP request to Ably, including the connection phase.boolean
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.Custom Local Device storage.Controls the log output of the library.int
Controls the verbosity of the logs output from the library.int
Enables a non-default Ably port to be specified.Proxy settingsboolean
Whether to tell Ably to wait for push REST requests to fully wait for all their effects before responding.boolean
If false, this disables the default behavior whereby the library queues messages on a connection in the disconnected or connecting states.Enables a non-default Ably host to be specified for realtime connections.long
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.Enables a connection to inherit the state of a previous connection that may have existed under a different instance of the Realtime library.Enables a non-default Ably host to be specified.long
This is a timeout when the connection enters the suspendedState.boolean
When false, the client will use an insecure connection.int
Enables a non-default Ably TLS port to be specified.Param[]
A set of key-value pairs that can be used to pass in arbitrary connection parameters, such as heartbeatInterval or remainPresentFor.boolean
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
ConstructorsConstructorDescriptionCreates a ClientOptions instance used to configure Rest and Realtime clientsClientOptions
(String key) Creates a ClientOptions instance used to configure Rest and Realtime clients -
Method Summary
-
Field Details
-
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 logLevelControls the verbosity of the logs output from the library. Levels include verbose, debug, info, warn and error.Spec: TO3b
-
logHandler
Controls the log output of the library. This is a function to handle each line of log output.Spec: TO3c
-
tls
public boolean tlsWhen 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
FIXME: unused -
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
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 portEnables a non-default Ably port to be specified. For development environments only. The default value is 80.Spec: TO3k4
-
tlsPort
public int tlsPortEnables a non-default Ably TLS port to be specified. For development environments only. The default value is 443.Spec: TO3k5
-
autoConnect
public boolean autoConnectWhen true, the client connects to Ably as soon as it is instantiated. You can set this to false and explicitly connect to Ably using theConnection.connect()
method. The default is true.Spec: RTC1b, TO3e
-
useBinaryProtocol
public boolean useBinaryProtocolWhen 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 queueMessagesIf 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 echoMessagesIf false, prevents messages originating from this connection being echoed back on the same connection. The default is true.Spec: RTC1a, TO3h
-
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
Proxy settings -
environment
Enables a custom environment to be used with the Ably service.Spec: RSC15b, TO3k1
-
idempotentRestPublishing
public boolean idempotentRestPublishingWhen 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 httpOpenTimeoutTimeout for opening a connection to Ably to initiate an HTTP request. The default is 4 seconds.Spec: TO3l3
-
httpRequestTimeout
public int httpRequestTimeoutTimeout for a client performing a complete HTTP request to Ably, including the connection phase. The default is 10 seconds.Spec: TO3l4
-
httpMaxRetryDuration
public int httpMaxRetryDurationDenotes elapsed time in which fallback host retries for HTTP requests will be attempted. Default is 15 seconds. Spec: TO3l6 -
httpMaxRetryCount
public int httpMaxRetryCountThe 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 realtimeRequestTimeoutTimeout 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 disconnectedRetryTimeoutWhen 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
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 suspendedRetryTimeoutThis 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.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 fallbackRetryTimeoutThe maximum time before HTTP requests are retried against the default endpoint. The default is 600 seconds.Spec: TO3l10
-
defaultTokenParams
When aAuth.TokenParams
object is provided, it overrides the client library defaults when issuing new Ably Tokens or AblyAuth.TokenRequest
.Spec: TO3j11
-
channelRetryTimeout
public int channelRetryTimeoutWhen a channel becomesChannelState.suspended
following a server initiatedChannelState.detached
, after this delay, if the channel is stillChannelState.suspended
and the connection isConnectionState.connected
, the client library will attempt to re-attach the channel automatically. The default is 15 seconds.Spec: RTL13b, TO3l7
-
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 asyncHttpThreadpoolSizeAllows the caller to specify a non-default size for the asyncHttp threadpool -
pushFullWait
public boolean pushFullWaitWhether to tell Ably to wait for push REST requests to fully wait for all their effects before responding. -
localStorage
Custom Local Device storage. In the case nothing is provided then a default implementation using SharedPreferences is used. -
addRequestIds
public boolean addRequestIdsWhen 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 theErrorInfo
returned to the user. The default is false.Spec: TO3p
-
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
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
Internal method- Returns:
- copy of client options
-
clearAuthOptions
public void clearAuthOptions()Internal methodclears all auth options
-