Java and Android Socketcluster Client

This SocketCluster Java/Android Client fork has the following differences from upstream:

• Jackson JSON parser is used, instead of JSON-java
• SocketCluster Minimal binary (sc-codec-min-bin) codec support. See Codecs section on usage example
• Underlying nv-websocket-client has been updated to the latest version
• Breaking: callback params now have Jackson JsonNode types, instead of upstream's Object

Important Note: Due to using jackson-databind this library is significantly bigger in size than upstream (~1.8 Mb), so if binary codec support is not needed, consider using upstream instead.

Overview

This client provides following functionality

• Support for emitting and listening to remote events
• Automatic reconnection
• Pub/sub
• Authentication (JWT)
• Binary codec support (sc-codec-min-bin included out-of-the-box)

License

Apache License, Version 2.0

Gradle

allprojects {
repositories {
jcenter()
maven { url "https://jitpack.io" }
}
}
...
dependencies {
implementation 'com.github.XDex:socketcluster-client-java:2.0.3'
}

Download

Description

Create instance of Socket class by passing url of socketcluster-server end-point

//Create a socket instanceStringurl="ws://localhost:8000/socketcluster/";
Socketsocket = newSocket(url);

Important Note : Default url to socketcluster end-point is always ws://somedomainname.com/socketcluster/.

Registering basic listeners

Implemented using BasicListener interface

socket.setListener(newBasicListener() {
publicvoidonConnected(Socketsocket, Map<String, List<String>> headers) {
System.out.println("Connected to endpoint");
}
publicvoidonDisconnected(Socketsocket, WebSocketFrameserverCloseFrame, WebSocketFrameclientCloseFrame, booleanclosedByServer) {
System.out.println("Disconnected from end-point");
}
publicvoidonConnectError(Socketsocket, WebSocketExceptionexception) {
System.out.println("Got connect error "+ exception);
}
publicvoidonSetAuthToken(Stringtoken, Socketsocket) {
System.out.println("Token is "+ token);
}
publicvoidonAuthentication(Socketsocket, Booleanstatus) {
if (status) {
System.out.println("socket is authenticated");
} else {
System.out.println("Authentication is required (optional)");
}
}
});

Connecting to server

• For connecting to server:

// This will send websocket handshake request to socketcluster-serversocket.connect();

• For connecting asynchronously to server:

// This will send websocket handshake request to socketcluster-serversocket.connectAsync();

• By default reconnection to server is not enabled, to enable it:

// This will set automatic reconnection to server with delay of 2 seconds and repeating it for 30 timessocket.setReconnection(newReconnectStrategy().setDelay(2000).setMaxAttempts(30));
socket.connect();

• To disable reconnection :

socket.setReconnection(null); 

• By default logging of messages is enabled, to disable:

socket.disableLogging();

Emitting and listening to events

Event emitter

• eventname is name of event and message can be String, boolean, Long or JsonNode

socket.emit(eventname, message);
// socket.emit("chat", "Hi");

• To send event with acknowledgement

socket.emit(eventname, message, newAck() {
publicvoidcall(StringeventName, JsonNodeerror, JsonNodedata) {
System.out.println("Got message for :" + eventName + " error is: " + error + " data is:" + data);
}
});

Event Listener

• For listening to events :

The object received can be String, Boolean, Long or JsonNode.

socket.on(eventname, newEmitter.Listener() {
publicvoidcall(StringeventName, JsonNodedata) {
System.out.println("Got message for: " + eventName + " data is: " + data);
}
}); 

• To send acknowledgement back to server

socket.on(eventname, newEmitter.AckListener() {
publicvoidcall(StringeventName, JsonNodeobject, Ackack) { System.out.println("Got message: " + object);
// ...if (error){
ack.call(eventName, error, null);
} else{
ack.call(eventName, null, data);
}
//Both error and data can be sent to serverack.call(eventName, error, data);
}
});

Codecs

Custom binary SocketCluster codecs are supported.
Support for sc-codec-min-bin is included out-of-the-box.

To enable a binary codec, just set it as follows on the SocketCluster Socket:

socket.setCodec(newMinBinCodec());

Custom binary codecs must implement the SocketClusterCodec interface.

Implementing Pub-Sub via channels

Creating channel

• For creating and subscribing to channels:

Socket.Channelchannel = socket.createChannel(channelName);
// Socket.Channel channel = socket.createChannel("yolo"); /** * without acknowledgement */channel.subscribe();
/** * with acknowledgement */channel.subscribe(newAck() {
publicvoidcall(StringchannelName, JsonNodeerror, JsonNodedata) {
if (error == null) {
System.out.println("Subscribed to channel " + channelName + " successfully");
}
}
});

• For getting list of created channels :

List <Socket.Channel> channels = socket.getChannels();

• To get channel by name :

Socket.Channelchannel = socket.getChannelByName("yolo");
//Returns null if channel of given name is not present

Publishing event on channel

• For publishing event :

// message can have any data type/** * without acknowledgement */channel.publish(message);
/** * with acknowledgement */channel.publish(message, newAck() {
publicvoidcall(StringchannelName, JsonNodeerror, JsonNodedata) {
if (error == null) {
System.out.println("Published message to channel " + channelName + " successfully");
}
}
});

Listening to channel

• For listening to channel event :

channel.onMessage(newEmitter.Listener() {
publicvoidcall(StringchannelName , JsonNodeobject) {
System.out.println("Got message for channel " + channelName + " data is " + data);
}
});

Unsubscribing a channel

/** * without acknowledgement */channel.unsubscribe();
/** * with acknowledgement */channel.unsubscribe(newAck() {
publicvoidcall(StringchannelName, JsonNodeerror, JsonNodedata) {
if (error == null) {
System.out.println("channel unsubscribed successfully");
}
}
}); 

Handling SSL connection with server

WebSocketFactory class is responsible for creating websocket instances and handling settings with server, for more information visit here

To get instance of WebSocketFactory class :

WebSocketFactoryfactory = socket.getFactorySettings();

The following is an example to set a custom SSL context to a WebSocketFactory instance. (Again, you don't have to call a setSSL* method if you use the default SSL configuration.)

// Create a custom SSL context.SSLContextcontext = NaiveSSLContext.getInstance("TLS");
// Set the custom SSL context.factory.setSSLContext(context);

NaiveSSLContext used in the above example is a factory class to create an SSLContext which naively accepts all certificates without verification. It's enough for testing purposes. When you see an error message "unable to find valid certificate path to requested target" while testing, try NaiveSSLContext.

Setting HTTP proxy with server

If a WebSocket endpoint needs to be accessed via an HTTP proxy, information about the proxy server has to be set to a WebSocketFactory instance before creating a WebSocket instance. Proxy settings are represented by ProxySettings class. A WebSocketFactory instance has an associated ProxySettings instance and it can be obtained by calling WebSocketFactory.getProxySettings() method.

// Get the associated ProxySettings instance.ProxySettingssettings = factory.getProxySettings();

ProxySettings class has methods to set information about a proxy server such as setHost method and setPort method. The following is an example to set a secure (https) proxy server.

// Set a proxy server.settings.setServer("https://proxy.example.com");

If credentials are required for authentication at a proxy server, setId method and setPassword method, or setCredentials method can be used to set the credentials. Note that, however, the current implementation supports only Basic Authentication.

// Set credentials for authentication at a proxy server.settings.setCredentials(id, password);

Star the repo. if you love the client :).