Skip to main content

Java client

The Java client calls the REST API from Java code, with typed objects in place of URLs and JSON. Spark, Flink, Trino and other Java applications use it. Each page of the REST reference shows the client code for its call under the Java tab, so this page covers only what every program needs first: adding the library, connecting and signing in.

Quick start​

The example connects to one metalake as a local user and lists its catalogs.

  1. Add the library to your build.

    build.gradle.kts
    dependencies {
      implementation("org.apache.gravitino:gravitino-client-java-runtime:1.3.1")
    }

  2. Connect and list the catalogs.

    ListCatalogs.java
    import org.apache.gravitino.Catalog;
    import org.apache.gravitino.client.GravitinoClient;

    public class ListCatalogs {
      public static void main(String[] args) {
        try (GravitinoClient client = GravitinoClient
            .builder("https://{gravitino_host}")
            .withMetalake("{metalake}")
            .withBasicAuth("{user}", "{password}")
            .build()) {
          for (Catalog catalog : client.listCatalogsInfo()) {
            System.out.println(catalog.name() + " " + catalog.type() + " " + catalog.provider());
          }
        }
      }
    }

    Each line names a catalog, its type, and its provider. To sign in through your identity provider instead, replace withBasicAuth as described in Sign in.

Add the library​

The client is published as one shaded jar. Use 1.3.1 or a later 1.3 release; in 1.3.0 a loaded view cannot carry tags. The client works with a server of the same or a later major and minor version, which Get server version reports, so a 1.3 client works with any 1.3 server.

build.gradle.kts
dependencies {
  implementation("org.apache.gravitino:gravitino-client-java-runtime:1.3.1")
}
pom.xml
<dependency>
  <groupId>org.apache.gravitino</groupId>
  <artifactId>gravitino-client-java-runtime</artifactId>
  <version>1.3.1</version>
</dependency>

Connect​

There are two clients. GravitinoAdminClient creates, lists and drops metalakes, and only service admins can use it. GravitinoClient works inside one metalake: catalogs, schemas, tables and everything below them, plus tags, policies, users, roles and jobs. The REST reference samples call them adminClient and client.

Create the clients
GravitinoAdminClient adminClient = GravitinoAdminClient
    .builder("https://{gravitino_host}")
    .withBasicAuth("{user}", "{password}")
    .build();

GravitinoClient client = GravitinoClient
    .builder("https://{gravitino_host}")
    .withMetalake("{metalake}")
    .withBasicAuth("{user}", "{password}")
    .build();

The URI is the server's address without /api. On connecting, the client checks that its version is compatible with the server's; withVersionCheckDisabled() turns the check off. Close a client when you are done with it, since both implement Closeable.

Sign in​

Pick the builder method that matches how the server authenticates. See Authentication for the server side of each.

Builder methodUse it for
withBasicAuth(user, password)The admin user and local users
withOAuth(tokenProvider)Users who sign in through your identity provider
withCustomTokenAuth(tokenProvider)A token your application obtains itself
Sign in with an OAuth 2 token
DefaultOAuth2TokenProvider tokenProvider = DefaultOAuth2TokenProvider.builder()
    .withUri("https://{oauth_host}")
    .withPath("{token_path}")
    .withCredential("{client_id}:{client_secret}")
    .withScope("{scope}")
    .build();

GravitinoClient client = GravitinoClient
    .builder("https://{gravitino_host}")
    .withMetalake("{metalake}")
    .withOAuth(tokenProvider)
    .build();

Configure​

withClientConfig sets the HTTP timeouts. An unknown property name raises an exception.

PropertyDescriptionDefault
gravitino.client.connectionTimeoutMsHTTP connection timeout, in milliseconds180000
gravitino.client.socketTimeoutMsHTTP socket timeout, in milliseconds180000
Set the client timeouts
GravitinoClient client = GravitinoClient
    .builder("https://{gravitino_host}")
    .withMetalake("{metalake}")
    .withBasicAuth("{user}", "{password}")
    .withClientConfig(Map.of(
        "gravitino.client.connectionTimeoutMs", "10000",
        "gravitino.client.socketTimeoutMs", "60000"))
    .build();

withHeaders adds HTTP headers to every request.

Errors​

A failed call throws an exception named for the problem, such as NoSuchCatalogException, TableAlreadyExistsException or ForbiddenException, from org.apache.gravitino.exceptions. The name matches the type field of the REST error response, which each reference page lists under its error status codes.

Last updated on