Giter Club home page Giter Club logo

immudb4j's Introduction

immudb4j License

Slack Discuss at immudb@googlegroups.com Coverage Maven Central

The Official immudb Client for Java 1.8 and above.

Contents

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>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.

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 1.4.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 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 Database

Creating a new database is quite simple:

    immuClient.createDatabase("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").getValue();

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").getValue();

    } (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):

        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();
        // ...
    }

Closing the client

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.

Contributing

We welcome contributions. Feel free to join the team!

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

immudb4j's People

Contributors

jeroiraz avatar dxps avatar giako avatar marcosanchotene avatar razikus avatar mmeloni avatar vchain-us-mgmt avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.