• 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

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.0</version>
  </dependency> 

• if using Gradle:

  compile 'io.codenotary:immudb4j:1.0.0'

immudb4j is currently hosted on both Maven Central and 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.

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

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.