centrifuge-java

Websocket client for Centrifugo server and Centrifuge library.

There is no v1 release of this library yet – API still evolves. At the moment patch version updates only contain backwards compatible changes, minor version updates can have backwards incompatible API changes.

Check out client SDK API specification to learn how this SDK behaves. It's recommended to read that before starting to work with this SDK as the spec covers common SDK behavior - describes client and subscription state transitions, main options and methods. Also check out examples folder.

The features implemented by this SDK can be found in SDK feature matrix.

Installation

Library available in Maven: https://search.maven.org/artifact/io.github.centrifugal/centrifuge-java

Javadoc online

http://www.javadoc.io/doc/io.github.centrifugal/centrifuge-java

Before you start

Centrifuge-java library uses Protobuf library (Lite version) for client protocol. This fact and the fact that Protobuf Lite uses reflection internally can cause connection errors when releasing your application with Android shrinking and obfuscation features enabled. See protocolbuffers/protobuf#6463 for details. To deal with this add the following Proguard rule into proguard-rules.pro file in your project:

-keepclassmembers class * extends com.google.protobuf.GeneratedMessageLite {
  <fields>;
}

More information about Android shrinking.

Basic usage

See example code in console Java example or in demo Android app

To use with Android don't forget to set INTERNET permission to AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Usage in background

When a mobile application goes to the background there are OS-specific limitations for established persistent connections - which can be silently closed shortly. Thus in most cases you need to disconnect from a server when app moves to the background and connect again when app goes to the foreground.

CI status

License

Library is available under the MIT license. See LICENSE for details.

For Contributors

This section contains an information for library contributors. You don't need generating protobuf code if you just want to use centrifuge-java in your project.

Generate proto

Make sure options set in client.proto:

option java_package = "io.github.centrifugal.centrifuge.internal.protocol";
option java_outer_classname = "Protocol";

Then:

protoc --java_out=lite:./ client.proto
mv io/github/centrifugal/centrifuge/internal/protocol/Protocol.java centrifuge/src/main/java/io/github/centrifugal/centrifuge/internal/protocol/Protocol.java
rm -r io/

For maintainer

release

Create configuration file gradle.properties in GRADLE_USER_HOME:

signing.keyId=<LAST_8_SYMBOLS_OF_KEY_ID>
signing.password=<PASSWORD>
signing.secretKeyRingFile=/Path/to/.gnupg/secring.gpg

ossrhUsername=<USERNAME>
ossrhPassword=<PASSWORD>

Bump version in centrifuge/build.gradle. Write changelog. Create new library tag. Then run:

./gradlew publish

Then follow instructions:

https://central.sonatype.org/pages/releasing-the-deployment.html

I.e.

1. Login here: https://oss.sonatype.org/
2. Go to Staging repositories
3. Find release, push Close button, wait
4. Push Release button

Special thanks

• Thanks to Maks Atygaev for initial library boilerplate