Skip to content

Java

Java Client

Nessie has a thin client designed to be incorporated into existing projects with minimum difficulty. The client is a thin layer over Nessie’s openapi Rest APIs.

To use the Nessie client, you can add it as a dependency to your Java project using Maven. The coordinates are:

<dependency>
  <groupId>org.projectnessie</groupId>
  <artifactId>nessie-client</artifactId>
  <version>0.16.0</version>
</dependency> 

For ease of integration with tools that carry many dependencies, the Nessie client’s dependencies are declared as optional. It is designed to work with any recent version of JAX-RS client (Jersey and Resteasy are both tested inside Nessie’s tests) + Jackson’s DataBinding and JAX-RS modules (any version from the last ~3+ years).

API

The NessieClientBuilder and concrete builder implementations (such as HttpClientBuilder) provide an easy way of configuring and building a NessieApi. The currently stable API that should be used is NessieApiV1, which can be instantiated as shown below:

import java.net.URI;
import java.util.List;
import org.projectnessie.client.api.NessieApiV1;
import org.projectnessie.client.http.HttpClientBuilder;
import org.projectnessie.model.Reference;

NessieApiV1 api = HttpClientBuilder.builder()
  .withUri(URI.create("http://localhost:19121/api/v1"))
  .build(NessieApiV1.class);

List<Reference> references = api.getAllReferences().get();
references.stream()
  .map(Reference::getName)
  .forEach(System.out::println);

The following subsections will outline how different actions can be done via that Nessie API.

Fetching details about a particular Reference

Fetches the Reference object of the main branch and then gets its hash

api.getReference().refName("main").get().getHash();

Creating a Reference

Creates a new branch dev that points to the main branch

Reference main = api.getReference().refName("main").get();
Reference branch =
    api.createReference()
        .sourceRefName(main.getName())
        .reference(Branch.of("dev", main.getHash()))
        .create();

Creates a new tag dev-tag that points to the main branch

Reference main = api.getReference().refName("main").get();
Reference tag =
    api.createReference()
        .sourceRefName(main.getName())
        .reference(Tag.of("dev-tag", main.getHash()))
        .create();

Assigning a Reference

Assigns a previously created devBranch2 to the dev branch

Reference dev = api.getReference().refName("dev").get();
api.assignBranch()
    .branchName("devBranch2")
    .hash(dev.getHash())
    .assignTo(dev)
    .assign();

Assigns a previously created dev-tag to the dev branch

Reference dev = api.getReference().refName("dev").get();
api.assignTag()
    .tagName("dev-tag")
    .hash(dev.getHash())
    .assignTo(dev)
    .assign();

Deleting a Reference

Deletes a previously created branch

api.deleteBranch()
    .branchName(dev.getName())
    .hash(dev.getHash())
    .delete();

Deletes a previously created tag

api.deleteTag()
    .tagName(devTag.getName())
    .hash(devTag.getHash())
    .delete();

Fetching the Server Configuration

NessieConfiguration config = api.getConfig();
config.getDefaultBranch();
config.getVersion();

Committing

Creates a new commit by adding metadata for an IcebergTable under the specified ContentKey instance represented by key and deletes content represented by key2

ContentKey key = ContentKey.of("table.name.space", "name");
ContentKey key2 = ContentKey.of("other.name.space", "name2");
IcebergTable icebergTable = IcebergTable.of("path1", 42L);
api.commitMultipleOperations()
    .branchName(branch)
    .hash(main.getHash())
    .operation(Put.of(key, icebergTable))
    .operation(Delete.of(key2))
    .commitMeta(CommitMeta.fromMessage("commit 1"))
    .commit();

Fetching Content

Fetches the content for a single ContentKey

ContentKey key = ContentKey.of("table.name.space", "name");
Map<ContentKey, Content> map = api.getContent().key(key).refName("dev").get();

Fetches the content for multiple ContentKey instances

List<ContentKey> keys =
  Arrays.asList(
  ContentKey.of("table.name.space", "name1"),
  ContentKey.of("table.name.space", "name2"),
  ContentKey.of("table.name.space", "name3"));
Map<ContentKey, Content> allContent = api.getContent().keys(keys).refName("dev").get();

Fetching the Commit Log

Fetches the commit log for the dev reference

LogResponse log = api.getCommitLog().refName("dev").get();

Fetching Entries

Fetches the entries for the dev reference

EntriesResponse entries = api.getEntries().refName("dev").get();

Merging

This merges fromBranch into the given intoBranch

api.mergeRefIntoBranch()
  .branchName("intoBranch")
  .hash(intoBranchHash)
  .fromRefName("fromBranch")
  .fromHash(fromHash)
  .merge();

Transplanting

Transplant/cherry-pick a bunch of commits from main into the dev branch

Branch dev = ...
api.transplantCommitsIntoBranch()
    .branchName(dev.getName())
    .hash(dev.getHash())
    .fromRefName("main")
    .hashesToTransplant(Collections.singletonList(api.getReference().refName("main").get().getHash()))
    .transplant()

Authentication

Nessie has multiple NessieAuthenticationProvider implementations that allow different client authentication mechanisms as can be seen below. The documentation for how to configure Nessie server authentication can be found here.

The BasicAuthenticationProvider allows connecting to a Nessie server that has BASIC authentication enabled. Note that BASIC is not supported in production and should only be used for development/testing.

NessieApiV1 api =
  HttpClientBuilder.builder()
  .withUri(URI.create("http://localhost:19121/api/v1"))
  .withAuthentication(BasicAuthenticationProvider.create("my_username", "very_secret"))
  .build(NessieApiV1.class);

The BearerAuthenticationProvider allows connecting to a Nessie server that has BEARER authentication enabled.

NessieApiV1 api =
  HttpClientBuilder.builder()
  .withUri(URI.create("http://localhost:19121/api/v1"))
  .withAuthentication(BearerAuthenticationProvider.create("bearerToken"))
  .build(NessieApiV1.class);