org.apache.gravitino.client

Class GravitinoClient

java.lang.Object

org.apache.gravitino.client.GravitinoClientBase

org.apache.gravitino.client.GravitinoClient

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable, SupportsCatalogs, TagOperations

public class GravitinoClient
extends GravitinoClientBase
implements SupportsCatalogs, TagOperations

Apache Gravitino Client for a user to interact with the Gravitino API, allowing the client to list, load, create, and alter Catalog.

It uses an underlying RESTClient to send HTTP requests and receive responses from the API.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GravitinoClient.ClientBuilder Builder class for constructing a GravitinoClient.

Nested classes/interfaces inherited from class org.apache.gravitino.client.GravitinoClientBase

GravitinoClientBase.Builder<T>

Field Summary

Fields inherited from class org.apache.gravitino.client.GravitinoClientBase

API_METALAKES_IDENTIFIER_PATH, API_METALAKES_LIST_PATH, restClient

Method Summary

Modifier and Type	Method and Description
Group	addGroup(java.lang.String group) Adds a new Group.
User	addUser(java.lang.String user) Adds a new User.
Catalog	alterCatalog(java.lang.String catalogName, CatalogChange... changes) Alter a catalog with specified identifier.
Tag	alterTag(java.lang.String name, TagChange... changes) Alter a tag under a metalake.
static GravitinoClient.ClientBuilder	builder(java.lang.String uri) Creates a new builder for constructing a GravitinoClient.
Catalog	createCatalog(java.lang.String catalogName, Catalog.Type type, java.lang.String provider, java.lang.String comment, java.util.Map<java.lang.String,java.lang.String> properties) Create a catalog with specified identifier.
Role	createRole(java.lang.String role, java.util.Map<java.lang.String,java.lang.String> properties, java.util.List<SecurableObject> securableObjects) Creates a new Role.
Tag	createTag(java.lang.String name, java.lang.String comment, java.util.Map<java.lang.String,java.lang.String> properties) Create a tag under a metalake.
boolean	deleteRole(java.lang.String role) Deletes a Role.
boolean	deleteTag(java.lang.String name) Delete a tag under a metalake.
boolean	dropCatalog(java.lang.String catalogName) Drop a catalog with specified identifier.
Group	getGroup(java.lang.String group) Gets a Group.
java.util.Optional<Owner>	getOwner(MetadataObject object) Get the owner of a metadata object.
Role	getRole(java.lang.String role) Gets a Role.
Tag	getTag(java.lang.String name) Get a tag by its name under a metalake.
User	getUser(java.lang.String user) Gets a User.
Role	grantPrivilegesToRole(java.lang.String role, MetadataObject object, java.util.List<Privilege> privileges) Grant privileges to a role.
Group	grantRolesToGroup(java.util.List<java.lang.String> roles, java.lang.String group) Grant roles to a group.
User	grantRolesToUser(java.util.List<java.lang.String> roles, java.lang.String user) Grant roles to a user.
java.lang.String[]	listCatalogs() List the name of all catalogs in the metalake.
Catalog[]	listCatalogsInfo() List all catalogs with their information in the metalake.
java.lang.String[]	listGroupNames() List the group names.
Group[]	listGroups() List the groups.
java.lang.String[]	listRoleNames() Lists the role names.
java.lang.String[]	listTags() List all the tag names under a metalake.
Tag[]	listTagsInfo() List all the tags with detailed information under a metalake.
java.lang.String[]	listUserNames() Lists the usernames.
User[]	listUsers() Lists the users.
Catalog	loadCatalog(java.lang.String catalogName) Load a catalog by its identifier.
boolean	removeGroup(java.lang.String group) Removes a Group.
boolean	removeUser(java.lang.String user) Removes a User.
Role	revokePrivilegesFromRole(java.lang.String role, MetadataObject object, java.util.List<Privilege> privileges) Revoke privileges from a role.
Group	revokeRolesFromGroup(java.util.List<java.lang.String> roles, java.lang.String group) Revoke roles from a group.
User	revokeRolesFromUser(java.util.List<java.lang.String> roles, java.lang.String user) Revoke roles from a user.
void	setOwner(MetadataObject object, java.lang.String ownerName, Owner.Type ownerType) Set the owner of a metadata object.
void	testConnection(java.lang.String catalogName, Catalog.Type type, java.lang.String provider, java.lang.String comment, java.util.Map<java.lang.String,java.lang.String> properties) Test whether a catalog can be created successfully with the specified parameters, without actually creating it.

Methods inherited from class org.apache.gravitino.client.GravitinoClientBase

checkMetalakeName, checkVersion, clientVersion, close, getVersion, loadMetalake, serverVersion

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.gravitino.SupportsCatalogs

catalogExists

Method Detail

listCatalogs

public java.lang.String[] listCatalogs()
                                throws NoSuchMetalakeException

Description copied from interface: SupportsCatalogs

List the name of all catalogs in the metalake.

Specified by:

listCatalogs in interface SupportsCatalogs

Returns:

The list of catalog's names.

Throws:

NoSuchMetalakeException - If the metalake does not exist.

listCatalogsInfo

public Catalog[] listCatalogsInfo()
                           throws NoSuchMetalakeException

Description copied from interface: SupportsCatalogs

List all catalogs with their information in the metalake.

Specified by:

listCatalogsInfo in interface SupportsCatalogs

Returns:

The list of catalog's information.

Throws:

NoSuchMetalakeException - If the metalake with namespace does not exist.

loadCatalog

public Catalog loadCatalog(java.lang.String catalogName)
                    throws NoSuchCatalogException

Description copied from interface: SupportsCatalogs

Load a catalog by its identifier.

Specified by:

loadCatalog in interface SupportsCatalogs

Parameters:

catalogName - the identifier of the catalog.

Returns:

The catalog.

Throws:

NoSuchCatalogException - If the catalog does not exist.

createCatalog

public Catalog createCatalog(java.lang.String catalogName,
                             Catalog.Type type,
                             java.lang.String provider,
                             java.lang.String comment,
                             java.util.Map<java.lang.String,java.lang.String> properties)
                      throws NoSuchMetalakeException,
                             CatalogAlreadyExistsException

Description copied from interface: SupportsCatalogs

Create a catalog with specified identifier.

The parameter "provider" is a short name of the catalog, used to tell Gravitino which catalog should be created. The short name should be the same as the CatalogProvider interface provided.

Specified by:

createCatalog in interface SupportsCatalogs

Parameters:

catalogName - the name of the catalog.

type - the type of the catalog.

provider - the provider of the catalog.

comment - the comment of the catalog.

properties - the properties of the catalog.

Returns:

The created catalog.

Throws:

NoSuchMetalakeException - If the metalake does not exist.

CatalogAlreadyExistsException - If the catalog already exists.

alterCatalog

public Catalog alterCatalog(java.lang.String catalogName,
                            CatalogChange... changes)
                     throws NoSuchCatalogException,
                            java.lang.IllegalArgumentException

Description copied from interface: SupportsCatalogs

Alter a catalog with specified identifier.

Specified by:

alterCatalog in interface SupportsCatalogs

Parameters:

catalogName - the identifier of the catalog.

changes - the changes to apply to the catalog.

Returns:

The altered catalog.

Throws:

NoSuchCatalogException - If the catalog does not exist.

java.lang.IllegalArgumentException - If the changes cannot be applied to the catalog.

dropCatalog

public boolean dropCatalog(java.lang.String catalogName)

Description copied from interface: SupportsCatalogs

Drop a catalog with specified identifier.

Specified by:

dropCatalog in interface SupportsCatalogs

Parameters:

catalogName - the name of the catalog.

Returns:

True if the catalog was dropped, false otherwise.

addUser

public User addUser(java.lang.String user)
             throws UserAlreadyExistsException,
                    NoSuchMetalakeException

Adds a new User.

Parameters:

user - The name of the User.

Returns:

The added User instance.

Throws:

UserAlreadyExistsException - If a User with the same name already exists.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If adding the User encounters storage issues.

removeUser

public boolean removeUser(java.lang.String user)
                   throws NoSuchMetalakeException

Removes a User.

Parameters:

user - The name of the User.

Returns:

True if the User was successfully removed, false only when there's no such user, otherwise it will throw an exception.

Throws:

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If removing the User encounters storage issues.

getUser

public User getUser(java.lang.String user)
             throws NoSuchUserException,
                    NoSuchMetalakeException

Gets a User.

Parameters:

user - The name of the User.

Returns:

The getting User instance.

Throws:

NoSuchUserException - If the User with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If getting the User encounters storage issues.

listUsers

public User[] listUsers()

Lists the users.

Returns:

The User list.

Throws:

NoSuchMetalakeException - If the Metalake with the given name does not exist.

listUserNames

public java.lang.String[] listUserNames()

Lists the usernames.

Returns:

The username list.

Throws:

NoSuchMetalakeException - If the Metalake with the given name does not exist.

addGroup

public Group addGroup(java.lang.String group)
               throws GroupAlreadyExistsException,
                      NoSuchMetalakeException

Adds a new Group.

Parameters:

group - The name of the Group.

Returns:

The Added Group instance.

Throws:

GroupAlreadyExistsException - If a Group with the same name already exists.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If adding the Group encounters storage issues.

removeGroup

public boolean removeGroup(java.lang.String group)
                    throws NoSuchMetalakeException

Removes a Group.

Parameters:

group - THe name of the Group.

Returns:

True if the Group was successfully removed, false only when there's no such group, otherwise it will throw an exception.

Throws:

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If removing the Group encounters storage issues.

getGroup

public Group getGroup(java.lang.String group)
               throws NoSuchGroupException,
                      NoSuchMetalakeException

Gets a Group.

Parameters:

group - The name of the Group.

Returns:

The getting Group instance.

Throws:

NoSuchGroupException - If the Group with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If getting the Group encounters storage issues.

listGroups

public Group[] listGroups()
                   throws NoSuchMetalakeException

List the groups.

Returns:

The Group list

Throws:

NoSuchMetalakeException - If the Metalake with the given name does not exist.

listGroupNames

public java.lang.String[] listGroupNames()
                                  throws NoSuchMetalakeException

List the group names.

Returns:

The group names list.

Throws:

NoSuchMetalakeException - If the Metalake with the given name does not exist.

getRole

public Role getRole(java.lang.String role)
             throws NoSuchRoleException,
                    NoSuchMetalakeException

Gets a Role.

Parameters:

role - The name of the Role.

Returns:

The getting Role instance.

Throws:

NoSuchRoleException - If the Role with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If getting the Role encounters storage issues.

deleteRole

public boolean deleteRole(java.lang.String role)
                   throws NoSuchMetalakeException

Deletes a Role.

Parameters:

role - The name of the Role.

Returns:

True if the Role was successfully deleted, false only when there's no such role, otherwise it will throw an exception.

Throws:

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If deleting the Role encounters storage issues.

createRole

public Role createRole(java.lang.String role,
                       java.util.Map<java.lang.String,java.lang.String> properties,
                       java.util.List<SecurableObject> securableObjects)
                throws RoleAlreadyExistsException,
                       NoSuchMetalakeException,
                       NoSuchMetadataObjectException

Creates a new Role.

Parameters:

role - The name of the Role.

properties - The properties of the Role.

securableObjects - The securable objects of the Role.

Returns:

The created Role instance.

Throws:

RoleAlreadyExistsException - If a Role with the same name already exists.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

NoSuchMetadataObjectException - If securable object doesn't exist

java.lang.RuntimeException - If creating the Role encounters storage issues.

grantRolesToUser

public User grantRolesToUser(java.util.List<java.lang.String> roles,
                             java.lang.String user)
                      throws NoSuchUserException,
                             NoSuchRoleException,
                             NoSuchMetalakeException

Grant roles to a user.

Parameters:

user - The name of the User.

roles - The names of the Role.

Returns:

The Group after granted.

Throws:

NoSuchUserException - If the User with the given name does not exist.

NoSuchRoleException - If the Role with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If granting roles to a user encounters storage issues.

grantRolesToGroup

public Group grantRolesToGroup(java.util.List<java.lang.String> roles,
                               java.lang.String group)
                        throws NoSuchGroupException,
                               NoSuchRoleException,
                               NoSuchMetalakeException

Grant roles to a group.

Parameters:

group - The name of the Group.

roles - The names of the Role.

Returns:

The Group after granted.

Throws:

NoSuchGroupException - If the Group with the given name does not exist.

NoSuchRoleException - If the Role with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If granting roles to a group encounters storage issues.

revokeRolesFromUser

public User revokeRolesFromUser(java.util.List<java.lang.String> roles,
                                java.lang.String user)
                         throws NoSuchUserException,
                                NoSuchRoleException,
                                NoSuchMetalakeException

Revoke roles from a user.

Parameters:

user - The name of the User.

roles - The names of the Role.

Returns:

The User after revoked.

Throws:

NoSuchUserException - If the User with the given name does not exist.

NoSuchRoleException - If the Role with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If revoking roles from a user encounters storage issues.

revokeRolesFromGroup

public Group revokeRolesFromGroup(java.util.List<java.lang.String> roles,
                                  java.lang.String group)
                           throws NoSuchGroupException,
                                  NoSuchRoleException,
                                  NoSuchMetalakeException

Revoke roles from a group.

Parameters:

group - The name of the Group.

roles - The names of the Role.

Returns:

The Group after revoked.

Throws:

NoSuchGroupException - If the Group with the given name does not exist.

NoSuchRoleException - If the Role with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

java.lang.RuntimeException - If revoking roles from a group encounters storage issues.

getOwner

public java.util.Optional<Owner> getOwner(MetadataObject object)
                                   throws NoSuchMetadataObjectException

Get the owner of a metadata object.

Parameters:

object - The metadata object

Returns:

The owner of the metadata object. If the metadata object doesn't set the owner, it will return Optional.empty().

Throws:

NoSuchMetadataObjectException - If the metadata object is not found.

setOwner

public void setOwner(MetadataObject object,
                     java.lang.String ownerName,
                     Owner.Type ownerType)
              throws NotFoundException

Set the owner of a metadata object.

Parameters:

object - The metadata object.

ownerName - The name of the owner

ownerType - The type of the owner, The owner can be a user or a group.

Throws:

NotFoundException - If the metadata object isn't found or the owner doesn't exist.

listRoleNames

public java.lang.String[] listRoleNames()
                                 throws NoSuchMetalakeException

Lists the role names.

Returns:

The role name list.

Throws:

NoSuchMetalakeException - If the Metalake with the given name does not exist.

grantPrivilegesToRole

public Role grantPrivilegesToRole(java.lang.String role,
                                  MetadataObject object,
                                  java.util.List<Privilege> privileges)
                           throws NoSuchRoleException,
                                  NoSuchMetadataObjectException,
                                  NoSuchMetalakeException,
                                  IllegalPrivilegeException

Grant privileges to a role.

Parameters:

role - The name of the role.

privileges - The privileges to grant.

object - The object is associated with privileges to grant.

Returns:

The role after granted.

Throws:

NoSuchRoleException - If the role with the given name does not exist.

NoSuchMetadataObjectException - If the metadata object with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

IllegalPrivilegeException - If any privilege can't be bind to the metadata object.

java.lang.RuntimeException - If granting roles to a role encounters storage issues.

revokePrivilegesFromRole

public Role revokePrivilegesFromRole(java.lang.String role,
                                     MetadataObject object,
                                     java.util.List<Privilege> privileges)
                              throws NoSuchRoleException,
                                     NoSuchMetadataObjectException,
                                     NoSuchMetalakeException,
                                     IllegalPrivilegeException

Revoke privileges from a role.

Parameters:

role - The name of the role.

privileges - The privileges to revoke.

object - The object is associated with privileges to revoke.

Returns:

The role after revoked.

Throws:

NoSuchRoleException - If the role with the given name does not exist.

NoSuchMetadataObjectException - If the metadata object with the given name does not exist.

NoSuchMetalakeException - If the Metalake with the given name does not exist.

IllegalPrivilegeException - If any privilege can't be bind to the metadata object.

java.lang.RuntimeException - If revoking privileges from a role encounters storage issues.

builder

public static GravitinoClient.ClientBuilder builder(java.lang.String uri)

Creates a new builder for constructing a GravitinoClient.

Parameters:

uri - The base URI for the Gravitino API.

Returns:

A new instance of the Builder class for constructing a GravitinoClient.

testConnection

public void testConnection(java.lang.String catalogName,
                           Catalog.Type type,
                           java.lang.String provider,
                           java.lang.String comment,
                           java.util.Map<java.lang.String,java.lang.String> properties)
                    throws java.lang.Exception

Test whether a catalog can be created successfully with the specified parameters, without actually creating it.

Specified by:

testConnection in interface SupportsCatalogs

Parameters:

catalogName - the name of the catalog.

type - the type of the catalog.

provider - the provider of the catalog.

comment - the comment of the catalog.

properties - the properties of the catalog.

Throws:

java.lang.Exception - if the test failed.

listTags

public java.lang.String[] listTags()
                            throws NoSuchMetalakeException

Description copied from interface: TagOperations

List all the tag names under a metalake.

Specified by:

listTags in interface TagOperations

Returns:

The list of tag names.

Throws:

NoSuchMetalakeException - If the metalake does not exist.

listTagsInfo

public Tag[] listTagsInfo()
                   throws NoSuchMetalakeException

Description copied from interface: TagOperations

List all the tags with detailed information under a metalake.

Specified by:

listTagsInfo in interface TagOperations

Returns:

The list of tags.

Throws:

NoSuchMetalakeException - If the metalake does not exist.

getTag

public Tag getTag(java.lang.String name)
           throws NoSuchTagException

Description copied from interface: TagOperations

Get a tag by its name under a metalake.

Specified by:

getTag in interface TagOperations

Parameters:

name - The name of the tag.

Returns:

The tag.

Throws:

NoSuchTagException - If the tag does not exist.

createTag

public Tag createTag(java.lang.String name,
                     java.lang.String comment,
                     java.util.Map<java.lang.String,java.lang.String> properties)
              throws TagAlreadyExistsException

Description copied from interface: TagOperations

Create a tag under a metalake.

Specified by:

createTag in interface TagOperations

Parameters:

name - The name of the tag.

comment - The comment of the tag.

properties - The properties of the tag.

Returns:

The created tag.

Throws:

TagAlreadyExistsException - If the tag already exists.

alterTag

public Tag alterTag(java.lang.String name,
                    TagChange... changes)
             throws NoSuchTagException,
                    java.lang.IllegalArgumentException

Description copied from interface: TagOperations

Alter a tag under a metalake.

Specified by:

alterTag in interface TagOperations

Parameters:

name - The name of the tag.

changes - The changes to apply to the tag.

Returns:

The altered tag.

Throws:

NoSuchTagException - If the tag does not exist.

java.lang.IllegalArgumentException - If the changes cannot be applied to the tag.

deleteTag

public boolean deleteTag(java.lang.String name)

Description copied from interface: TagOperations

Delete a tag under a metalake.

Specified by:

deleteTag in interface TagOperations

Parameters:

name - The name of the tag.

Returns:

True if the tag is deleted, false if the tag does not exist.