Android | Java |
---|---|
|
|
A Java Realtime and REST client library for Ably Realtime, the realtime messaging and data delivery service.
Visit https://www.ably.io/documentation for a complete API reference and more examples.
Reference the library by including a compile dependency reference in your gradle build file.
For Java:
compile 'io.ably:ably-java:1.0.1'
For Android:
compile 'io.ably:ably-android:1.0.1'
The library is hosted on the Jcenter repository, so you need to ensure that the repo is referenced also; IDEs will typically include this by default:
repositories {
jcenter()
}
Previous releases of the Java library included a downloadable JAR; however we now only support installation via Maven/Gradle from the Jcenter repository. If you want to use a standalone fat JAR for (ie containing all dependencies), it can be generated via a gradle task (see building below); note that this is the "Java" (JRE) library variant only; Android is now supported via an AAR and there is no self-contained AAR build option.
For Java, JRE 7 or later is required. Note that the Java Unlimited JCE extensions must be installed in the Java runtime environment.
For Android, 4.0 (API level 14) or later is required.
Please refer to the documentation for a full realtime API reference.
The examples below 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);
Please refer to the documentation for a full REST API reference.
The examples below 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();
The library consists of JRE-specific library (in java/
) and an Android-specific library (in android/
). The libraries are largely common-sourced; the lib/
directory contains the common parts.
A gradle wrapper is included so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands, given below, is:
./gradlew <task name>
but on Windows there is a batch file:
gradlew.bat <task name>
The JRE-specific library JAR is built with:
./gradlew java:jar
There is also a task to build a fat JAR containing the dependencies:
./gradlew java:fullJar
The Android-specific library AAR is built with:
./gradlew android:assemble
(The ANDROID_HOME
environment variable must be set appropriately.)
A gradle wrapper is included so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands, given below, is:
./gradlew <task name>
but on Windows there is a batch file:
gradlew.bat <task name>
Tests are based on JUnit, and there are separate suites for the REST and Realtime libraries, with gradle tasks for the JRE-specific library:
./gradlew java:testRestSuite
./gradlew java:testRealtimeSuite
To run tests against a specific host, specify in the environment:
env ABLY_ENV=staging ./gradlew testRealtimeSuite
Tests will run against sandbox by default.
Tests can be run on the Android-specific library. An Android device must be connected, either a real device or the Android emulator.
./gradlew android:connectedAndroidTest
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 this file README.md and build.gradle) and commit the changes
- Run
github_changelog_generator
to automate the update of the CHANGELOG. Once the CHANGELOG has completed, manually change theUnreleased
heading and link with the current version number such asv1.0.1
. Also ensure that theFull Changelog
link points to the new version tag instead of theHEAD
. Commit this change. - Add a tag and push to origin such as
git tag v1.0.1 && git push origin v1.0.1
- Run
gradle java:assemble
to build the JRE-specific JARs for this release - Run
gradle android:assemble
to build the Android AAR for this release
- Go to the home page for the package; eg https://bintray.com/ably-io/ably/ably-java. Select New version, enter the new version such as "1.0.1" in name and save
- Run
./gradlew java:assembleRelease
locally to generate the files - Open local relative folder such as
/lib/build/release/1.0.1/
- Then go to the new version in JFrog Bintray; eg https://bintray.com/ably-io/ably/ably-java/1.0.1, then click on the link to upload via the UI in the "Upload files" section
- Type in
io/ably/ably-java/1.0.1
into "Target Repository Path" ensuring the correct version is included. The drag in the files injava/build/release/1.0.1/
- You will see a notice "You have 8 unpublished item(s) for this version", make sure you click "Publish". Wait a few minutes and check that your version has all the necessary files at https://bintray.com/ably-io/ably/ably-java/1.0.1?sort=&order=#files/io/ably/ably-java/1.0.1 for example.
- Update the README text in Bintray.
- Visit https://github.com/ably/ably-java/tags and
Add release notes
for the release including links to the changelog entry and the JCenter releases.
Similarly for the Android release at https://bintray.com/ably-io/ably/ably-android.
Run gradle android:assembleRelease
locally to generate the files, and drag in the files in
android/build/release/1.0.1/
.
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(
./gradlew java:testRestSuite java:testRealtimeSuite android:connectedAndroidTest
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Copyright (c) 2015-2017 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.