{"id":18436050,"url":"https://github.com/codenotary/immudb4j","last_synced_at":"2026-03-14T00:16:28.224Z","repository":{"id":38818698,"uuid":"286514484","full_name":"codenotary/immudb4j","owner":"codenotary","description":"Java SDK for immudb","archived":false,"fork":false,"pushed_at":"2024-09-16T10:51:54.000Z","size":16535,"stargazers_count":35,"open_issues_count":10,"forks_count":9,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-12-15T20:58:02.805Z","etag":null,"topics":["cryptographic-verifications","immudb","immutability","java","sdk-java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codenotary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-10T15:39:23.000Z","updated_at":"2024-08-30T14:03:07.000Z","dependencies_parsed_at":"2024-05-20T09:51:55.506Z","dependency_job_id":"9a04c550-5073-4401-bbf5-d5603970cf4e","html_url":"https://github.com/codenotary/immudb4j","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codenotary%2Fimmudb4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codenotary","download_url":"https://codeload.github.com/codenotary/immudb4j/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230454432,"owners_count":18228392,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cryptographic-verifications","immudb","immutability","java","sdk-java"],"created_at":"2024-11-06T06:10:02.191Z","updated_at":"2026-03-14T00:16:28.179Z","avatar_url":"https://github.com/codenotary.png","language":"Java","readme":"# immudb4j [![License](https://img.shields.io/github/license/codenotary/immudb4j)](LICENSE)\n\n[![Slack](https://img.shields.io/badge/join%20slack-%23immutability-brightgreen.svg)](https://slack.vchain.us/)\n[![Discuss at immudb@googlegroups.com](https://img.shields.io/badge/discuss-immudb%40googlegroups.com-blue.svg)](https://groups.google.com/group/immudb)\n[![Coverage](https://coveralls.io/repos/github/codenotary/immudb4j/badge.svg?branch=master)](https://coveralls.io/github/codenotary/immudb4j?branch=master)\n[![Maven Central](https://img.shields.io/maven-central/v/io.codenotary/immudb4j.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22io.codenotary%22%20AND%20a:%22immudb4j%22)\n\n### The Official [immudb] Client for Java 1.8 and above.\n\n[immudb]: https://immudb.io/\n\n\n## Contents\n\n- [Introduction](#introduction)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Supported Versions](#supported-versions)\n- [Quickstart](#quickstart)\n- [Step by step guide](#step-by-step-guide)\n    * [Creating a Client](#creating-a-client)\n    * [User sessions](#user-sessions)\n    * [Creating a database](#creating-a-database)\n    * [Setting the active database](#setting-the-active-database)\n    * [Standard Read and Write](#standard-read-and-write)\n    * [Verified or Safe read and write](#verified-or-safe-read-and-write)\n    * [Multi-key read and write](#multi-key-read-and-write)\n    * [Closing the client](#creating-a-database)\n- [Contributing](#contributing)\n\n## Introduction\n\nimmudb4j implements a [gRPC] immudb client, based on [immudb's official protobuf definition].\u003cbr/\u003e\nIt exposes a minimal and simple to use API for applications, while the cryptographic verifications and state update protocol implementation \nare fully implemented internally by this client.\n\nThe latest validated immudb state may be kept in the local file system using default `FileImmuStateHolder`.\u003cbr/\u003e\nPlease read [immudb Research Paper] for details of how immutability is ensured by [immudb].\n\n[gRPC]: https://grpc.io/\n[immudb Research Paper]: https://immudb.io/\n[immudb]: https://immudb.io/\n[immudb's official protobuf definition](https://github.com/codenotary/immudb/blob/master/pkg/api/schema/schema.proto)\n\n## Prerequisites\n\nimmudb4j assumes you have access to a running immudb server.\u003cbr/\u003e\nRunning `immudb` on your system is very simple, please refer to this [immudb QuickStart](https://docs.immudb.io/master/quickstart.html) page.\n\n## Installation\n\nJust include immudb4j as a dependency in your project:\n- if using Maven:\n  ```xml\n  \u003cdependency\u003e\n      \u003cgroupId\u003eio.codenotary\u003c/groupId\u003e\n      \u003cartifactId\u003eimmudb4j\u003c/artifactId\u003e\n      \u003cversion\u003e1.0.1\u003c/version\u003e\n  \u003c/dependency\u003e \n  ```\n- if using Gradle:\n  ```groovy\n  compile 'io.codenotary:immudb4j:1.0.1'\n  ```\n\n`immudb4j` is currently hosted on both [Maven Central].\n\n[Maven Central]: https://search.maven.org/artifact/io.codenotary/immudb4j\n\n## Supported Versions\n\nimmudb4j supports the [latest immudb server] release.\n\n[latest immudb server]: https://github.com/codenotary/immudb/releases/tag/v1.5.0\n\n## Quickstart\n\n[Hello Immutable World!] example can be found in `immudb-client-examples` repo.\n\n[Hello Immutable World!]: https://github.com/codenotary/immudb-client-examples/tree/master/java\n\nFollow its [README](https://github.com/codenotary/immudb-client-examples/blob/master/java/README.md) to build and run it.\n\n## Step-by-step Guide\n\n### Creating a Client\n\nThe following code snippets show how to create a client.\n\nUsing default configuration:\n```java\n    ImmuClient immuClient = ImmuClient.newBuilder().build();\n```\n\nSetting `immudb` url and port:\n```java\n    ImmuClient immuClient = ImmuClient.newBuilder()\n                                .withServerUrl(\"localhost\")\n                                .withServerPort(3322)\n                                .build();\n```\n\nCustomizing the `State Holder`:\n```java\n    FileImmuStateHolder stateHolder = FileImmuStateHolder.newBuilder()\n                                        .withStatesFolder(\"./my_immuapp_states\")\n                                        .build();\n\n    ImmuClient immuClient = ImmuClient.newBuilder()\n                                      .withStateHolder(stateHolder)\n                                      .build();\n```\n\n### User Sessions\n\nUse `openSession` and `closeSession` methods to initiate and terminate user sessions:\n\n```java\n    immuClient.openSession(\"defaultdb\", \"usr1\", \"pwd1\");\n\n    // Interact with immudb using open session.\n    //...\n\n    immuClient.closeSession();\n```\n\n### Creating a Database\n\nCreating a new database is quite simple:\n\n```java\n    immuClient.createDatabase(\"db1\");\n```\n\n### Standard Read and Write\n\nimmudb provides standard read and write operations that behave as in a standard\nkey-value store i.e. no cryptographic verification is involved. Such operations\nmay be used when validations can be postponed.\n\n```java\n    client.set(\"k123\", new byte[]{1, 2, 3});\n    \n    byte[] v = client.get(\"k123\").getValue();\n```\n\n### Verified or Safe Read and Write\n\nimmudb provides built-in cryptographic verification for any entry. The client\nimplements the mathematical validations while the application uses as a standard\nread or write operation:\n\n```java\n    try {\n        client.verifiedSet(\"k123\", new byte[]{1, 2, 3});\n    \n        byte[] v = client.verifiedGet(\"k123\").getValue();\n\n    } (catch VerificationException e) {\n\n        // Check if it is a data tampering detected case!\n\n    }\n```\n\n### Multi-key Read and Write\n\nTransactional multi-key read and write operations are supported by immudb and immudb4j.\n\nAtomic multi-key write (all entries are persisted or none):\n\n```java\n        final List\u003cKVPair\u003e kvs = KVListBuilder.newBuilder()\n            .add(new KVPair(\"sga-key1\", new byte[] {1, 2}))\n            .add(new KVPair(\"sga-key2\", new byte[] {3, 4}))\n            .entries();\n\n        try {\n            immuClient.setAll(kvs);\n        } catch (CorruptedDataException e) {\n            // ...\n        }\n```\n\nAtomic multi-key read (all entries are retrieved or none):\n\n```java\n    List\u003cString\u003e keys = Arrays.asList(key1, key2, key3);\n    List\u003cEntry\u003e result = immuClient.getAll(keys);\n\n    for (Entry entry : result) {\n        byte[] key = entry.getKey();\n        byte[] value = entry.getValue();\n        // ...\n    }\n```\n\n### Closing the client\n\nApart from the `closeSession`, for closing the connection with immudb server use the `shutdown` operation:\n \n```java\n    immuClient.shutdown();\n```\n\nNote: After the shutdown, a new client needs to be created to establish a new connection.\n\n## Contributing\n\nWe welcome contributions. Feel free to join the team!\n\nTo report bugs or get help, use [GitHub's issues].\n\n[GitHub's issues]: https://github.com/codenotary/immudb4j/issues\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenotary%2Fimmudb4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodenotary%2Fimmudb4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodenotary%2Fimmudb4j/lists"}