immudb4j

The Official immudb Client for Java 1.8 and above.

Contents

• Introduction
• Prerequisites
• Installation
• Supported Versions
• Quickstart
• Step by step guide
  • Creating a Client
  • User sessions
  • Creating a database
  • Setting the active database
  • Standard Read and Write
  • Verified or Safe read and write
  • Multi-key read and write
  • Closing the client
• Contributing

Introduction

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

Prerequisites

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.

Installation

Just include immudb4j as a dependency in your project:

• if using Maven:

  <dependency>
      <groupId>io.codenotary</groupId>
      <artifactId>immudb4j</artifactId>
      <version>0.9.0.6</version>
  </dependency> 

• if using Gradle:

  compile 'io.codenotary:immudb4j:0.9.0.6'

immudb4j is currently hosted on both Maven Central and Github Packages.

How to use immudb4j packages from Github Packages

immudb4j Github Package repository needs to be included with authentication. When using Maven, it means to include immudb4j Github Package in your ~/.m2/settings.xml file. See Configuring Apache Maven for use with GitHub Packages and Configuring Gradle for use with GitHub Packages at Github Packages.

Supported Versions

immudb4j supports the latest immudb server release, that is 0.9.1 at the time of updating this document.

Quickstart

Hello Immutable World! example can be found in immudb-client-examples repo.

Follow its README to build and run it.

Step-by-step Guide

Creating a Client

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();

User Sessions

Use login and logout methods to initiate and terminate user sessions:

    immuClient.login("usr1", "pwd1");

    // Interact with immudb using logged-in user.
    //...

    immuClient.logout();

Creating a Database

Creating a new database is quite simple:

    immuClient.createDatabase("db1");

Setting the Active Database

Specify the active database with:

    immuClient.useDatabase("db1");

Standard Read and Write

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");

Verified or Safe Read and Write

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");

    } (catch VerificationException e) {

        // Check if it is a data tampering detected case!

    }

Multi-key Read and Write

Transactional multi-key read and write operations are supported by immudb and immudb4j.

Atomic multi-key write (all entries are persisted or none):

        String key1 = "sga-key1";
        byte[] val1 = new byte[] { 1 };
        String key2 = "sga-key2";
        byte[] val2 = new byte[] { 2, 3 };

        List<KV> kvs = Arrays.asList(
                        new KVPair(key1, val1), 
                        new KVPair(key2, val2));

        KVList kvList = KVList.newBuilder().addAll(kvs).build();
        try {
            immuClient.setAll(kvList);
        } catch (CorruptedDataException e) {
            // ...
        }

Atomic multi-key read (all entries are retrieved or none):

    List<String> keys = Arrays.asList(key1, key2, key3);
    List<KV> result = immuClient.getAll(keys);

    for (KV kv : result) {
        byte[] key = kv.getKey();
        byte[] value = kv.getValue();
        // ...
    }

Closing the client

Apart from the logout, 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.

Contributing

We welcome contributions. Feel free to join the team!

To report bugs or get help, use GitHub's issues.