actioncable-client-java

This is the actioncable client library for Java. Please see Action Cable Overview to understand actioncable itself.

Usage

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.

Basic

// 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();

Passing Parameters to Channel

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());

Custom Subscription Interface

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);

Options

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 okHttpClientFactory is not set, just create OkHttpClient by new OkHttpClient().

  options.okHttpClientFactory = new Connection.Options.OkHttpClientFactory() {
      @Override
      public OkHttpClient createOkHttpClient() {
          final OkHttpClient client = new OkHttpClient();
          client.networkInterceptors().add(new StethoInterceptor());
          return client;
      }
  };

Authentication

How to authenticate a request depends on the architecture you choose.

Authenticate by HTTP Header

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);

Authenticate by Query Params

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);

Authenticate by Cookie

CookieManager cookieManager = new CookieManager();
// Some setup
...
options.cookieHandler = cookieManager;

Consumer consumer = ActionCable.createConsumer(uri, options);

Proguard Rules

-keep class com.hosopy.actioncable.** { *; }
-keep interface com.hosopy.actioncable._* { *; }

License

MIT