The Official immudb Client for Java 1.8 and above.
- Introduction
- Prerequisites
- Installation
- Supported Versions
- Quickstart
- Step by step guide
- Contributing
immudb4j implements a gRPC immudb client, based on [immudb's official protobuf definition].
It exposes a minimal and simple to use API for applications, while the cryptographic verifications and state update protocol implementation
are fully implemented internally by this client.
The latest validated immudb state may be kept in the local file system using default FileImmuStateHolder.
Please read immudb Research Paper for details of how immutability is ensured by immudb.
immudb's official protobuf definition
immudb4j assumes you have access to a running immudb server.
Running immudb on your system is very simple, please refer to this immudb QuickStart page.
Just include immudb4j as a dependency in your project:
- if using Maven:
<dependency> <groupId>io.codenotary</groupId> <artifactId>immudb4j</artifactId> <version>1.0.1</version> </dependency>
- if using Gradle:
compile 'io.codenotary:immudb4j:1.0.1'
immudb4j is currently hosted on both Maven Central.
immudb4j supports the latest immudb server release.
Hello Immutable World! example can be found in immudb-client-examples repo.
Follow its README to build and run it.
The following code snippets show how to create a client.
Using default configuration:
ImmuClient immuClient = ImmuClient.newBuilder().build();Setting immudb url and port:
ImmuClient immuClient = ImmuClient.newBuilder()
.withServerUrl("localhost")
.withServerPort(3322)
.build();Customizing the State Holder:
FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()
.withStatesFolder("./my_immuapp_states")
.build();
ImmuClient immuClient = ImmuClient.newBuilder()
.withStateHolder(stateHolder)
.build();Use openSession and closeSession methods to initiate and terminate user sessions:
immuClient.openSession("defaultdb", "usr1", "pwd1");
// Interact with immudb using open session.
//...
immuClient.closeSession();Creating a new database is quite simple:
immuClient.createDatabase("db1");immudb provides standard read and write operations that behave as in a standard key-value store i.e. no cryptographic verification is involved. Such operations may be used when validations can be postponed.
client.set("k123", new byte[]{1, 2, 3});
byte[] v = client.get("k123").getValue();immudb provides built-in cryptographic verification for any entry. The client implements the mathematical validations while the application uses as a standard read or write operation:
try {
client.verifiedSet("k123", new byte[]{1, 2, 3});
byte[] v = client.verifiedGet("k123").getValue();
} (catch VerificationException e) {
// Check if it is a data tampering detected case!
}Transactional multi-key read and write operations are supported by immudb and immudb4j.
Atomic multi-key write (all entries are persisted or none):
final List<KVPair> kvs = KVListBuilder.newBuilder()
.add(new KVPair("sga-key1", new byte[] {1, 2}))
.add(new KVPair("sga-key2", new byte[] {3, 4}))
.entries();
try {
immuClient.setAll(kvs);
} catch (CorruptedDataException e) {
// ...
}Atomic multi-key read (all entries are retrieved or none):
List<String> keys = Arrays.asList(key1, key2, key3);
List<Entry> result = immuClient.getAll(keys);
for (Entry entry : result) {
byte[] key = entry.getKey();
byte[] value = entry.getValue();
// ...
}Apart from the closeSession, for closing the connection with immudb server use the shutdown operation:
immuClient.shutdown();Note: After the shutdown, a new client needs to be created to establish a new connection.
We welcome contributions. Feel free to join the team!
To report bugs or get help, use GitHub's issues.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent