This is the actioncable client library for Java. Please see Action Cable Overview to understand actioncable itself.
Gradle
repositories {
jcenter()
maven { url "https://jitpack.io" }
}
dependencies {
compile 'com.github.hosopy:actioncable-client-java:0.1.2'
}This Library uses google/gson to parse and compose JSON strings.
Please see user guide to know about GSON API.
// 1. Setup
URI uri = new URI("ws://cable.example.com");
Consumer consumer = ActionCable.createConsumer(uri);
// 2. Create subscription
Channel appearanceChannel = new Channel("AppearanceChannel");
Subscription subscription = consumer.getSubscriptions().create(appearanceChannel);
subscription
.onConnected(new Subscription.ConnectedCallback() {
@Override
public void call() {
// Called when the subscription has been successfully completed
}
}).onRejected(new Subscription.RejectedCallback() {
@Override
public void call() {
// Called when the subscription is rejected by the server
}
}).onReceived(new Subscription.ReceivedCallback() {
@Override
public void call(JsonElement data) {
// Called when the subscription receives data from the server
}
}).onDisconnected(new Subscription.DisconnectedCallback() {
@Override
public void call() {
// Called when the subscription has been closed
}
}).onFailed(new Subscription.FailedCallback() {
@Override
public void call(ActionCableException e) {
// Called when the subscription encounters any error
}
});
// 3. Establish connection
consumer.connect();
// 4. Perform any action
subscription.perform("away");
// 5. Perform any action using JsonObject(GSON)
JsonObject params = new JsonObject();
params.addProperty("foo", "bar");
subscription.perform("appear", params);Channel chatChannel = new Channel("ChatChannel");
chatChannel.addParam("room", "Best Room");
Subscription subscription = consumer.getSubscriptions().create(chatChannel);Supported parameter type is Number, String, Boolean and JsonElement(GSON).
chatChannel.addParam("room_id", 1);
chatChannel.addParam("room", "Best Room");
chatChannel.addParam("private", true);
chatChannel.addParam("params", new JsonObject());You can perform any action by calling Subscription#perform(), but you can define custom interfaces having methods.
public interface ChatSubscription extends Subscription {
/*
* Equivalent:
* perform("join")
*/
@Perform("join")
void join();
/*
* Equivalent:
* perform("send_message", JsonObjectFactory.fromJson("{body: \"...\", private: true}"))
*/
@Perform("send_message")
void sendMessage(@Data("body") String body, @Data("private") boolean isPrivate);
}Supported parameter type is Number, String, Boolean and JsonElement(GSON).
To instantiate the custom subscription, pass the interface when you create a subscription.
Channel chatChannel = new Channel("ChatChannel");
ChatSubscription subscription = consumer.getSubscriptions().create(appearanceChannel, ChatSubscription.class);
consumer.open();
subscription.join();
subscription.sendMessage("Hello", true);URI uri = new URI("ws://cable.example.com");
Consumer.Options options = new Consumer.Options();
options.reconnection = true;
Consumer consumer = ActionCable.createConsumer(uri, options);Below is a list of available options.
-
sslContext
options.sslContext = yourSSLContextInstance;
-
hostnameVerifier
options.hostnameVerifier = yourHostnameVerifier;
-
cookieHandler
options.cookieHandler = yourCookieManagerInstance;
-
query
Map<String, String> query = new HashMap(); query.put("foo", "bar"); options.query = query;
-
headers
Map<String, String> headers = new HashMap(); headers.put("X-FOO", "bar"); options.headers = headers;
-
reconnection
- If reconnection is true, the client attempts to reconnect to the server when underlying connection is stale.
- Default is
false.
options.reconnection = false;
-
reconnectionMaxAttempts
- The maximum number of attempts to reconnect.
- Default is
30.
options.reconnectionMaxAttempts = 30;
-
okHttpClientFactory
- Factory instance to create your own OkHttpClient.
- If
okHttpClientFactoryis not set, just create OkHttpClient bynew OkHttpClient().
options.okHttpClientFactory = new Connection.Options.OkHttpClientFactory() { @Override public OkHttpClient createOkHttpClient() { final OkHttpClient client = new OkHttpClient(); client.networkInterceptors().add(new StethoInterceptor()); return client; } };
How to authenticate a request depends on the architecture you choose.
Consumer.Options options = new Consumer.Options();
Map<String, String> headers = new HashMap();
headers.put("Authorization", "Bearer xxxxxxxxxxx");
options.headers = headers;
Consumer consumer = ActionCable.createConsumer(uri, options);Consumer.Options options = new Consumer.Options();
Map<String, String> query = new HashMap();
query.put("access_token", "xxxxxxxxxx");
options.query = query;
Consumer consumer = ActionCable.createConsumer(uri, options);CookieManager cookieManager = new CookieManager();
// Some setup
...
options.cookieHandler = cookieManager;
Consumer consumer = ActionCable.createConsumer(uri, options);MIT