A Java Realtime and REST client library for Ably.io, the realtime messaging service.
Visit https://www.ably.io/documentation for a complete API reference and more examples.
The Realtime library for Java is downloadable as a JAR at our Github releases page. You can either download the full JAR which includes all dependencies, or just the library but it will be your responsibility to ensure alld dependencies are met.
Please refer to the documentation.
JRE 7 or later is required. Note that the Java Unlimited JCE extensions must be installed in the runtime environment.
The library consists of a generic java library (in lib/) and a separate Android test project (in android-test/).
The base library jar is built with:
gradle lib:jar
There is also a task to build a fat jar containing the dependencies:
gradle fullJar
Tests are based on JUnit, and there are separate suites for the REST and Realtime libraries, with gradle tasks:
gradle testRestSuite
gradle testRealtimeSuite
To run tests against a specific host, specify in the environment:
export ABLY_ENV=staging; gradle testRealtimeSuite
Tests will run against sandbox by default.
Download the latest JAR or grab via Gradle:
compile 'io.ably:ably-java:0.8.2'and add following repo for a sub-dependency,
maven { url "https://raw.github.com/paddybyers/Java-WebSocket/mvn-repo/" }All examples assume a client has been created as follows:
AblyRealtime ably = new AblyRealtime("xxxxx");AblyRealtime will attempt to connect automatically once new instance is created. Also, it offers API for listening connection state changes.
ably.connection.on(new ConnectionStateListener() {
@Override
public void onConnectionStateChanged(ConnectionStateChange state) {
System.out.println("New state is " + change.current.name());
switch (state.current) {
case connected: {
// Successful connection
break;
}
case failed: {
// Failed connection
break;
}
}
}
});And it offers API for listening specific connection state changes.
ably.connection.on(ConnectionState.connected, new ConnectionStateListener() {
@Override
public void onConnectionStateChanged(ConnectionStateChange state) {
/* Do something */
}
});Given:
Channel channel = ably.channels.get("test");Subscribe to all events:
channel.subscribe(new MessageListener() {
@Override
public void onMessage(Message[] messages) {
for(Message message : messages) {
System.out.println("Received `" + message.name + "` message with data: " + message.data);
}
}
});or subscribe to certain events:
String[] events = new String[] {"event1", "event2"};
channel.subscribe(events, new MessageListener() {
@Override
public void onMessage(Message[] messages) {
System.out.println("Received `" + messages[0].name + "` message with data: " + message[0].data);
}
});channel.publish("greeting", "Hello World!", new CompletionListener() {
@Override
public void onSuccess() {
System.out.println("Message successfully sent");
}
@Override
public void onError(ErrorInfo reason) {
System.err.println("Unable to publish message; err = " + reason.message);
}
});PaginatedResult<Message> result = channel.history(null);
System.out.println(result.items().length + " messages received in first page");
while(result.hasNext()) {
result = result.getNext();
System.out.println(result.items().length + " messages received in next page");
}channel.presence.enter("john.doe", new CompletionListener() {
@Override
public void onSuccess() {
// Successfully entered to the channel
}
@Override
public void onError(ErrorInfo reason) {
// Failed to enter channel
}
});PaginatedResult<PresenceMessage> result = channel.presence.history(null);
System.out.println(result.items().length + " messages received in first page");
while(result.hasNext()) {
result = result.getNext();
System.out.println(result.items().length + " messages received in next page");
}Channel extends EventEmitter that emits channel state changes, and listening those events is possible with ChannelStateListener
ChannelStateListener listener = new ChannelStateListener() {
@Override
public void onChannelStateChanged(ChannelState state, ErrorInfo reason) {
System.out.println("Channel state changed to " + state.name());
if (reason != null) System.out.println(reason.toString());
}
};You can register using
channel.on(listener);and after you are done listening channel state events, you can unregister using
channel.off(listener);If you are interested with specific events, it is possible with providing extra ChannelState value.
channel.on(ChannelState.attached, listener);All examples assume a client and/or channel has been created as follows:
AblyRest ably = new AblyRest("xxxxx");
Channel channel = ably.channels.get("test");Given messages below
Message[] messages = new Message[]{new Message("myEvent", "Hello")};Sharing synchronously,
channel.publish(messages);Sharing asynchronously,
channel.publishAsync(messages, new CompletionListener() {
@Override
public void onSuccess() {
System.out.println("Message successfully sent");
}
@Override
public void onError(ErrorInfo reason) {
System.err.println("Unable to publish message; err = " + reason.message);
}
});PaginatedResult<Message> result = channel.history(null);
System.out.println(result.items().length + " messages received in first page");
while(result.hasNext()) {
result = result.getNext();
System.out.println(result.items().length + " messages received in next page");
}PaginatedResult<PresenceMessage> result = channel.presence.get(null);
System.out.println(result.items().length + " messages received in first page");
while(result.hasNext()) {
result = result.getNext();
System.out.println(result.items().length + " messages received in next page");
}PaginatedResult<PresenceMessage> result = channel.presence.history(null);
System.out.println(result.items().length + " messages received in first page");
while(result.hasNext()) {
result = result.getNext();
System.out.println(result.items().length + " messages received in next page");
}TokenDetails tokenDetails = ably.auth.requestToken(null, null);
System.out.println("Success; token = " + tokenRequest);PaginatedResult<Stats> stats = ably.stats(null);
System.out.println(result.items().length + " messages received in first page");
while(result.hasNext()) {
result = result.getNext();
System.out.println(result.items().length + " messages received in next page");
}long serviceTime = ably.time();This library uses semantic versioning. For each release, the following needs to be done:
- Replace all references of the current version number with the new version number (check pom.xml and build.gradle) and commit the changes
- Run
github_changelog_generatorto automate the update of the CHANGELOG. Once the CHANGELOG has completed, manually change theUnreleasedheading and link with the current version number such asv0.8.1. Also ensure that theFull Changeloglink points to the new version tag instead of theHEAD. Commit this change. - Add a tag and push to origin such as
git tag v0.8.1 && git push origin v0.8.1 - Run
gradle lib:jar && gradle fullJarto build the JARs for this release - Visit https://github.com/ably/ably-java/tags and
Add release notesfor the release, then attach the generated JARs in the folderlib/build/libs
Please visit http://support.ably.io/ for access to our knowledgebase and to ask for any assistance.
You can also view the community reported Github issues.
To see what has changed in recent versions of Bundler, see the CHANGELOG.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Ensure you have added suitable tests and the test suite is passing(
ant test) - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Copyright (c) 2015 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.