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 {
implementation '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); // or specify some options URI uri = new URI("ws://cable.example.com"); Consumer.Options options = new Consumer.Options(); options.reconnection = true; options.pingInterval = 30l; options.pingTimeUnit = TimeUnit.SECONDS; Consumer consumer = ActionCable.createConsumer(uri, options); // 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(); if(consumer.isConnected()) { System.out.println("Consumer connected!"); } // 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); // 6. Unsubscribe & close connection consumer.unsubscribeAndDisconnect();
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"); headers.put("Origin", "https://your-origin.tld"); 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);
-keep class com.hosopy.actioncable.** { *; } -keep interface com.hosopy.actioncable._* { *; }
MIT