https://github.com/hstreamdb/hstreamdb-java
Java Client for HStreamDB
https://github.com/hstreamdb/hstreamdb-java
Last synced: 8 months ago
JSON representation
Java Client for HStreamDB
- Host: GitHub
- URL: https://github.com/hstreamdb/hstreamdb-java
- Owner: hstreamdb
- License: apache-2.0
- Created: 2021-07-07T07:12:04.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2024-02-18T07:14:02.000Z (over 2 years ago)
- Last Synced: 2025-05-08T02:39:32.988Z (about 1 year ago)
- Language: Kotlin
- Homepage:
- Size: 5.75 MB
- Stars: 6
- Watchers: 2
- Forks: 8
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# hstreamdb-java
[](https://search.maven.org/artifact/io.hstream/hstreamdb-java)
[](https://javadoc.io/doc/io.hstream/hstreamdb-java/0.17.0)
[](https://s01.oss.sonatype.org/content/repositories/snapshots/io/hstream/hstreamdb-java/0.17.0-SNAPSHOT/)
[](https://hstreamdb.github.io/hstreamdb-java/javadoc/)
This is the official Java client library for [HStreamDB](https://hstream.io/).
**Please use the latest released version.**
**The latest release is v0.17.0, which requires HStreamDB v0.17.0 .**
## Content
- [Installation](#installation)
- [Maven](#maven)
- [Gradle](#gradle)
- [Example Usage](#example-usage)
- [Connect to HStreamDB](#connect-to-hstreamdb)
- [Work with Streams](#work-with-streams)
- [Write Data to a Stream](#write-data-to-a-stream)
- [Consume Data from a Stream](#consume-data-from-a-subscription)
- [Read Data from a Stream Shard](#read-data-from-a-stream-shard)
## Installation
The library artifact is published in Maven central,
available at [hstreamdb-java](https://search.maven.org/artifact/io.hstream/hstreamdb-java).
### Maven
For Maven Users, the library can be included easily like this:
```xml
io.hstream
hstreamdb-java
0.17.0
```
### Gradle
For Gradle Users, the library can be included easily like this:
```groovy
implementation 'io.hstream:hstreamdb-java:0.17.0'
```
## Example Usage
Here we will show you some simple examples to use hstreamdb-client,
you can find the complete examples in [hstreamdb-java-examples](https://github.com/hstreamdb/hstreamdb-java-examples),
for more detail on introduction and usage, please check the [guides](https://docs.hstream.io/write/write.html).
### Connect to HStreamDB
```java
import io.hstream.*;
public class ConnectExample {
public static void main(String[] args) throws Exception {
final String serviceUrl = "localhost:6570";
HStreamClient client = HStreamClient.builder().serviceUrl(serviceUrl).build();
System.out.println("Connected");
client.close();
}
}
```
### Work with Streams
```java
// get a list of streams
for(Stream stream: client.listStreams()) {
System.out.println(stream.getStreamName());
}
// create a new stream
client.createStream("test_stream");
// create a new stream with 5 replicas
client.createStream("test_stream", 5);
// delete a stream
client.deleteStream("test_stream");
```
### Write Data to a Stream
```java
Producer producer = client.newProducer().stream("test_stream").build();
// write raw records
Random random = new Random();
byte[] rawRecord = new byte[100];
random.nextBytes(rawRecord);
Record recordR = Record.newBuilder().rawRecord(rawRecord).build();
CompletableFuture future = producer.write(recordR);
// write hRecords
HRecord hRecord = HRecord.newBuilder()
.put("key1", 10)
.put("key2", "hello")
.put("key3", true)
.build();
Record recordH = Record.newBuilder().hRecord(hRecord).build();
CompletableFuture future = producer.write(recordH);
// buffered writes
BatchSetting batchSetting =
BatchSetting.newBuilder()
.recordCountLimit(100)
.bytesLimit(4096)
.ageLimit(100)
.build();
FlowControlSetting flowControlSetting =
FlowControlSetting.newBuilder()
.bytesLimit(40960)
.build();
BufferedProducer batchedProducer =
client.newBufferedProducer().stream("test_stream")
.batchSetting(batchSetting)
.flowControlSetting(flowControlSetting)
.build();
for(int i = 0; i < 1000; ++i) {
random.nextBytes(rawRecord);
Record recordB = Record.newBuilder().rawRecord(rawRecord).build();
batchedProducer.write(recordB);
}
// flush and close batchedProducer
batchedProducer.close();
```
**Please do not write both binary data and hrecord in one stream.**
### Consume Data from a Subscription
```java
// first, create a subscription for the stream
Subscription subscription =
Subscription
.newBuilder()
.subscription("my_subscription")
.stream("my_stream")
.ackTimeoutSeconds(600)
.build();
client.createSubscription(subscription);
// second, create a consumer attach to the subscription
Consumer consumer =
client
.newConsumer()
.subscription("my_subscription")
.rawRecordReceiver(
((receivedRawRecord, responder) -> {
System.out.println(receivedRawRecord.getRecordId());
responder.ack();
}))
.build();
// third, start the consumer
consumer.startAsync().awaitRunning();
System.out.println("the consumer is started");
```
### Read Data from a Stream Shard
```java
Reader reader =
client
.newReader()
.readerId("my_readerId")
.streamName("my_stream")
.shardId("my_shardId")
.build();
List records = reader.read(10).join();
reader.close();
```