Big Bang Client SDK
The Big Bang Client SDK for Android and Java helps you create realtime applications in seconds! It makes event streaming and data synchronization a snap!
Installation - Android
The native Android client can be installed with a dependency manager like Gradle and Maven, or obtained via direct download.
Gradle
If you are using Gradle to build your project, add the following custom repository and dependency to your build.gradle
repositories {
maven { url "https://dl.bintray.com/bigbang/maven" }
}
dependencies {
compile ("io.bigbang.client:android:0.0.4")
}
Maven
For Maven builds, add the following custom repository and dependency to your pom.xml
<repositories>
<repository>
<id>bigbang</id>
<name>Big Bang SDK Repository</name>
<url>https://dl.bintray.com/bigbang/maven</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>io.bigbang.client</groupId>
<artifactId>android</artifactId>
<version>0.0.4</version>
<scope>compile</scope>
</dependency>
</dependencies>
Android Permissions
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
<uses-permission android:name="android.permission.INTERNET" />
</manifest>
Big Bang requires internet access. Make sure to add android.permission.INTERNET
permission to your AndroidManifest.xml
Download
Download the Android binary release here. Unzip the archive and add the included jars to your application’s classpath.
Installation - Java
Non-Android Java applications should use the standard Java SDK.
Gradle
If you are using Gradle to build your project, add the following custom repository and dependency to your build.gradle
repositories {
maven { url "https://dl.bintray.com/bigbang/maven" }
}
dependencies {
compile ("io.bigbang.client:bigbang-client-java:0.0.4")
}
Maven
For Maven builds, add the following custom repository and dependency to your pom.xml
<repositories>
<repository>
<id>bigbang</id>
<name>Big Bang SDK Repository</name>
<url>https://dl.bintray.com/bigbang/maven</url>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>io.bigbang.client</groupId>
<artifactId>bigbang-client-java</artifactId>
<version>0.0.4</version>
<scope>compile</scope>
</dependency>
</dependencies>
Download
Download the full binary release here. Unzip the archive and add the included jars to your application’s classpath.
Servers
Big Bang manages your realtime infrastructure for you. Simply connect your clients and apps to your Big Bang URL. You can use http://demo.bigbang.io
to try things out. When you are ready, you can create your own application at https://www.getbigbang.com/.
Overview
You will work with three resources when using Big Bang. First, you will need to manage your connection to our servers. Once you have established a connection, you will subscribe to a Channel. All shared information is scoped to a Channel. You can publish and subscribe one-time messages. If you want to give all subscribers a constantly updated state of your data, you can publish and subscribe ChannelData.
Connection
Connecting your app to Big Bang is easy.
Android
final Handler bigBangHandler = new Handler(getMainLooper());
BigBangClient client = new AndroidBigBangClient(new Action<Runnable>() {
@Override
public void result(Runnable result) {
bigBangHandler.post(result);
}
});
client.connect("https://demo.bigbang.io", new Action<ConnectionError>() {
@Override
public void result(ConnectionError error) {
if (error != null) {
Log.i("bigbang", error.getMessage());
} else {
Log.i("bigbang", "Connected!");
}
}
});
The Android SDK uses a special constructor to make sure events from the Big Bang SDK are called in your desired UI thread. All network activity happens safely in the background. Here we pass in a android.os.Handler
associated with the main android.os.Looper
.
Java
BigBangClient client = new DefaultBigBangClient();
client.connect("https://demo.bigbang.io", new Action<ConnectionError>() {
@Override
public void result(ConnectionError error) {
if (error != null) {
System.out.println(error.getMessage());
} else {
System.out.println("Connected!");
}
}
});
Plain Java applications should use the default client and constructor.
Basics
client.connect(String url, Action<ConnectionError> connectHandler)
Connect to a Big Bang application at url.
Params
- url
java.lang.String
HTTP or HTTPS URL to your application. - callback (
Error
)
client.disconnect()
Disconnect from the server.
client.getClientId()
Your unique identifier for this session. This identifies you to the server and to other users.
Returns java.lang.String
clientId
Subscribe
client.subscribe("example-channel", new Action2<ChannelError, Channel>() {
@Override
public void result(ChannelError err, Channel channel) {
if (err != null) {
System.err.println(err);
} else {
System.out.println("Subscribed to channel " + channel.getName());
}
}
});
Disconnect
client.disconnected(new Action<Void>() {
@Override
public void result(Void result) {
System.out.println("Client disconnected");
}
});
client.disconnected(Action<Void> callback)
Fired when the client has been disconnected, either from calling disconnect() or for reasons beyond your control.
Channel
Group together multiple clients in a channel to share information. Channels are publish/subscribe. You can subscribe to a Channel to get any messages that are published to it. You can publish a message to send it to all subscribers.
Basics
Channel channel = client.getChannel("example-channel");
client.getChannel(String channelName)
Get a reference to the Channel object for the subscribed channel called channelName.
Params
- channelName
java.lang.String
Returns Channel
client.subscribe("example-channel", new Action2<ChannelError, Channel>() {
@Override
public void result(ChannelError err, Channel channel) {
if (err != null) {
System.err.println(err);
} else {
System.out.println("Subscribed to channel " + channel.getName());
}
}
});
client.subscribe(String channelName, Action2<ChannelError, Channel> callback)
Subscribe to a channel called channelName. channel will be a Channel object.
Params
- channelName
java.lang.String
- callback (
ChannelError
,Channel
)
channel.unsubscribe(Action<Void> callback)
Unsubscribe from the current channel.
channel.getSubscribers()
Returns an java.util.Set<java.lang.String>
containing the clientIds of the current subscribers on this channel.
Publish
JsonObject json = new JsonObject();
json.putString("message", "hello");
channel.publish(json);
channel.publish(JsonObject content, Action<ChannelError> callback)
Publish content to the channel. content must be an object or array.
Params
- content
io.bigbang.protocol.JsonObject
(JSON) - callback
ChannelError
if publish fails or is rejected
Subscribe
channel.onMessage(new Action<ChannelMessage>() {
@Override
public void result(ChannelMessage msg) {
System.out.println(msg.getPayload().getBytesAsJSON());
}
});
channel.onMessage(Action<ChannelMessage> handler)
Fired when a message is received on the channel.
channel.onJoin(new Action<String>() {
@Override
public void result(String result) {
System.out.println("clientId " + result + " joined the channel.");
}
});
channel.onJoin(Action<String> join)
Fired when a subscriber joins the channel.
channel.onLeave(new Action<String>() {
@Override
public void result(String result) {
System.out.println("clientId " + result + " left the channel.");
}
});
channel.onLeave(Action leave)
Fired when a subscriber leaves the channel.
ChannelData
ChannelData objects are used to store the state of your data. ChannelData persist as long as the Channel is active and they are automatically synchronized to all subscribers of the channel.
Basics
channel.getNamespaces()
Get the current ChannelData namespace names as an java.util.Set<java.lang.String>
.
Returns ChannelData
unless no namespaces exist. Returns null if no namespaces exist.
ChannelData channelData = channel.getChannelData();
channel.getChannelData()
Returns a ChannelData object for the default namespace.
ChannelData channelData = channel.getChannelData("my-namespace");
channel.getChannelData(String namespace)
Returns a ChannelData object for the given namespace. Namespaces can be used to organize your channel’s data.
Params
- namespace
java.lang.String namespace
Returns ChannelData
channelData.get(String key)
Params
- key
java.lang.String
Returns io.bigbang.protocol.JsonElement
unless the key doesn’t exist. Returns null if the key doesn’t exist.
JsonObject json = channelData.get("myKey", JsonObject.class);
channelData.get(java.lang.String key, java.lang.Class<T> type)
Params
- key
java.lang.String
Returns the type Class<T>
unless the key doesn’t exist. Returns null if the key doesn’t exist.
Publish
JsonObject msg = new JsonObject();
msg.putString("message", "hello channeldata!");
channelData.put("myKey", msg);
channelData.put(String key, JsonElement value)
Set the value for key.
Params
- key
java.lang.String
- value
io.bigbang.protocol.JsonElement
Subscribe
channelData.onAdd(new Action2<String, JsonElement>() {
@Override
public void result(String key, JsonElement val) {
System.out.println("added " + key + " => " + val);
}
});
channelData.onAdd(Action2<String, JsonElement> add)
Fires when a new key and value is added.
channelData.onUpdate(new Action2<String, JsonElement>() {
@Override
public void result(String key, JsonElement val) {
System.out.println("updated " + key + " => " + val);
}
});
channelData.onUpdate(Action2<String, JsonElement> update)
Fires when a key’s value is updated.
channelData.onRemove(new Action<String>() {
@Override
public void result(String key) {
System.out.println("removed " + key);
}
});
channelData.onRemove(Action<String> remove)
Fired when a key (and it’s value) is removed.
channelData.on("myKey", new Action2<JsonElement, ChannelData.Operation>() {
@Override
public void result(JsonElement e, ChannelData.Operation op) {
System.out.println("key operation is " + op);
}
});
channelData.on(String key, Action2 value)
Fired when anything happens to key. value will be the new value, except in the case of a remove operation returning null instead. This event is an easy way to monitor a single key.
Maintenance
channelData.remove("myKey");
channelData.remove(java.lang.String key)
Remove the value associated with key.
Params
- key
java.lang.String