Skip to content
Java library for interacting with Streamr APIs: publishing and subscribing to data, creating streams, etc.
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.idea init subsequent resend requests (#14) May 16, 2019
gradle/wrapper wip: initial commit Jun 5, 2018
src Resend functions (#16) May 20, 2019
.gitignore
.travis.yml disable uploadArchives May 21, 2019
LICENSE License under Apache 2.0 (#3) Jan 7, 2019
README.md 1.0.0 to Maven Central and update README May 21, 2019
build.gradle comment out uploadArchives (#17) May 22, 2019
gradlew wip: initial commit Jun 5, 2018
settings.gradle refactor package name Jan 7, 2019
streamr-client-java_integrationTest.iml init versionning for StreamMessage (#4) Jan 24, 2019
streamr-client-java_main.iml init versionning for StreamMessage (#4) Jan 24, 2019
streamr-client-java_test.iml init versionning for StreamMessage (#4) Jan 24, 2019
streamr-java-client.iml wip: initial commit Jun 5, 2018
streamr-java-client.ipr init versionning for StreamMessage (#4) Jan 24, 2019

README.md

Build Status

Java client library for Streamr

Using this library, you can easily interact with Streamr over HTTP and websocket APIs from Java-based applications.

This library is work-in-progress. It is currently in a MVP stage covering a very basic subset of functionality including:

Installation

This library is published to the Maven Central repository.

Using Maven

In your pom.xml, add the repository:

<repositories>
  <repository>
    <url>https://dl.bintray.com/ethereum/maven</url>
  </repository>
  ...
</repositories>

And the artifact itself:

<dependencies>
  <dependency>
    <groupId>com.streamr</groupId>
    <artifactId>client</artifactId>
    <version>1.0.0</version>
  </dependency>
  ...
</dependencies>

Using Gradle

In your build.gradle, add the repository:

repositories {
    maven {
        url "https://dl.bintray.com/ethereum/maven/"
    }
}

And the artifact itself:

dependencies {
    implementation 'com.streamr:client:1.0.0'
}

Usage

Authentication

To authenticate as a Streamr user, provide an AuthenticationMethod instance. We have two concrete classes that extend AuthenticationMethod:

  • ApiKeyAuthenticationMethod(String apiKey)
  • EthereumAuthenticationMethod(String ethereumPrivateKey)

To authenticate with an API key, create an ApiKeyAuthenticationMethod instance and pass it to the StreamrClient constructor:

StreamrClient client = new StreamrClient(new ApiKeyAuthenticationMethod(myApiKey)); 

The library will automatically fetch a session token using the provided API key to allow authenticated requests to be made.

To authenticate with an Ethereum account, create an EthereumAuthenticationMethod instance and pass it to the StreamrClient constructor:

StreamrClient client = new StreamrClient(new EthereumAuthenticationMethod(myEthereumPrivateKey)); 

The library will automatically initiate a challenge-response protocol to allow you to prove that you own the Ethereum private key without revealing it. You will be identified with the associated Ethereum public address. At the end of the protocol, the library will fetch a session token to allow authenticated requests to be made.

You can access public resources without authenticating. In this case you can create the instance without any arguments:

StreamrClient client = new StreamrClient(); 

Creating Streams

You create Streams via the create(Stream) method, passing in a prototype Stream object with fields set as you wish. The method returns the Stream object that was actually created.

Stream created = client.create(new Stream("Stream name", "Stream description"));

Looking up Streams

You can look up Streams by id:

Stream stream = client.getStream("id-of-the-stream");

Or by the name of the Stream (expects an unique result):

Stream stream = client.getStreamByName("My Fancy Stream");

Publishing events to Streams

Events in Streams are key-value pairs, represented in Java as Map objects. Below is an example of creating an event payload and publishing it into a Stream:

// Create the message payload, which is represented as a Map
Map<String, Object> msg = new LinkedHashMap<>();
msg.put("foo", "bar");
msg.put("random", Math.random());

// Then publish it!
client.publish(stream, msg);

All events are timestamped. The above example assigns the current timestamp to the new event, but you can also provide a timestamp explicitly:

client.publish(stream, msg, new Date());

Subscribing to events from Streams

By subscribing to Streams, your application gets immediately notified about new events in the Stream. You provide a MessageHandler which gets called with new events.

Subscription sub = client.subscribe(stream, new MessageHandler() {
    @Override
    void onMessage(Subscription s, StreamMessage message) {
        // Here you can react to the latest message
        System.out.println(message.getPayload().toString());
    }
})

Unsubscribing from Streams

To stop receiving events from a Stream, pass the Subscription object you got when subscribing to the unsubscribe method:

client.unsubscribe(sub);

TODO

This library is work in progress. At least the following will be done, probably sooner than later:

  • Covering all of the Stream API
  • Covering the API endpoints for other resources than Streams

This library is officially developed and maintained by the Streamr core dev team, but community contributions are very welcome!

You can’t perform that action at this time.