actioncable-client-kotlin (Updated)
fork of a fork for raw response
Note
I decided to fork this repo because hosopy is not updating his project anymore. If you want can use this forked version you can read the instructions below.
This is the actioncable client library for Kotlin. Please see Action Cable Overview to understand actioncable itself.
Usage
Requirements
- Kotlin 1.1.4-3 or later
- kotlinx.coroutines (experimental in Kotlin 1.1)
Gradle
repositories {
jcenter()
maven { url "https://jitpack.io" }
}
dependencies {
implementation 'com.github.WSAyan:actioncable-client-kotlin:1.0.0'
}
Basic
// 1. Setup
val uri = URI("ws://cable.example.com")
val consumer = ActionCable.createConsumer(uri)
// 2. Create subscription
val appearanceChannel = Channel("AppearanceChannel")
val subscription = consumer.subscriptions.create(appearanceChannel)
subscription.onConnected = {
// Called when the subscription has been successfully completed
}
subscription.onRejected = {
// Called when the subscription is rejected by the server
}
subscription.onReceived = { data: Any? ->
// Called when the subscription receives data from the server
// Possible types...
when (data) {
is Int -> { }
is Long -> { }
is BigInteger -> { }
is String -> { }
is Double -> { }
is Boolean -> { }
is JsonObject -> { }
is JsonArray<*> -> { }
}
}
subscription.onDisconnected = {
// Called when the subscription has been closed
}
subscription.onFailed = { error ->
// Called when the subscription encounters any error
}
// 3. Establish connection
consumer.connect()
// 4. Perform any action
subscription.perform("away")
// 5. Perform any action with params
subscription.perform("hello", mapOf("name" to "world"))
Passing Parameters to Channel
val chatChannel = Channel("ChatChannel", mapOf("room_id" to 1))
The parameter container is Map<String, Any?>
and is converted to JsonObject(Klaxon)
internally.
To know what type of value can be passed, please read Klaxon user guide.
Passing Parameters to Subscription#perform
subscription.perform("send", mapOf(
"comment" to mapOf(
"text" to "This is string.",
"private" to true,
"images" to arrayOf(
"http://example.com/image1.jpg",
"http://example.com/image2.jpg"
)
)
))
The parameter container is Map<String, Any?>
and is converted to JsonObject(Klaxon)
internally.
To know what type of value can be passed, please read Klaxon user guide.
Options
val uri = URI("ws://cable.example.com")
val options = Consumer.Options()
options.connection.reconnection = true
val consumer = ActionCable.createConsumer(uri, options)
Below is a list of available options.
-
sslContext
options.connection.sslContext = yourSSLContextInstance
-
hostnameVerifier
options.connection.hostnameVerifier = yourHostnameVerifier
-
cookieHandler
options.connection.cookieHandler = yourCookieManagerInstance
-
query
options.connection.query = mapOf("user_id" to "1")
-
headers
options.connection.headers = mapOf("X-Foo" to "Bar")
-
reconnection
- If reconnection is true, the client attempts to reconnect to the server when underlying connection is stale.
- Default is
false
.
options.connection.reconnection = false
-
reconnectionMaxAttempts
- The maximum number of attempts to reconnect.
- Default is
30
.
options.connection.reconnectionMaxAttempts = 30
-
okHttpClientFactory
- Factory instance to create your own OkHttpClient.
- If
okHttpClientFactory
is not set, just create OkHttpClient byOkHttpClient()
.
options.connection.okHttpClientFactory = { OkHttpClient().also { it.networkInterceptors().add(StethoInterceptor()) } }
Authentication
How to authenticate a request depends on the architecture you choose.
Authenticate by HTTP Header
val options = Consumer.Options()
options.connection.headers = mapOf("Authorization" to "Bearer xxxxxxxxxxx")
val consumer = ActionCable.createConsumer(uri, options)
Authenticate by Query Params
val options = Consumer.Options()
options.connection.query = mapOf("access_token" to "xxxxxxxxxxx")
val consumer = ActionCable.createConsumer(uri, options)
Authenticate by Cookie
val cookieManager = CookieManager()
// Some setup
...
options.connection.cookieHandler = cookieManager
val consumer = ActionCable.createConsumer(uri, options)
License
MIT