org.apache.gravitino.client

Class GravitinoMetalake

java.lang.Object

org.apache.gravitino.dto.MetalakeDTO

org.apache.gravitino.client.GravitinoMetalake

All Implemented Interfaces:

Auditable, SupportsRoles, Metalake, SupportsCatalogs, TagOperations

public class GravitinoMetalake
extends MetalakeDTO
implements SupportsCatalogs, TagOperations, SupportsRoles

Apache Gravitino Metalake is the top-level metadata repository for users. It contains a list of catalogs as sub-level metadata collections. With GravitinoMetalake, users can list, create, load, alter and drop a catalog with specified identifier.

Field Summary

Fields inherited from interface org.apache.gravitino.Metalake

PROPERTY_IN_USE

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 the catalog with specified identifier by applying the changes.
Tag	alterTag(java.lang.String name, TagChange... changes) Alter a tag under the current metalake.
static org.apache.gravitino.client.GravitinoMetalake.Builder	builder()
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 new catalog with specified identifier, type, comment and properties.
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 the current metalake.
boolean	deleteRole(java.lang.String role) Deletes a Role.
boolean	deleteTag(java.lang.String name) Delete a tag under the current metalake.
void	disableCatalog(java.lang.String catalogName) Disable a catalog.
boolean	dropCatalog(java.lang.String catalogName, boolean force) Drop a catalog with specified name.
void	enableCatalog(java.lang.String catalogName) Enable a catalog.
boolean	equals(java.lang.Object o)
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 the current 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.
Role	grantPrivilegesToRole(java.lang.String role, MetadataObject object, java.util.Set<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[]	listBindingRoleNames() List all the role names associated with this metadata object.
java.lang.String[]	listCatalogs() List all the catalogs under this metalake.
Catalog[]	listCatalogsInfo() List all the catalogs with their information under this metalake.
java.lang.String[]	listGroupNames() Lists the group names
Group[]	listGroups() Lists 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 the current metalake.
java.lang.String[]	listUserNames() Lists the usernames.
User[]	listUsers() Lists the users.
Catalog	loadCatalog(java.lang.String catalogName) Load the catalog with specified 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) Deprecated.
Role	revokePrivilegesFromRole(java.lang.String role, MetadataObject object, java.util.Set<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.
SupportsRoles	supportsRoles()
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.dto.MetalakeDTO

auditInfo, comment, hashCode, name, properties

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.apache.gravitino.SupportsCatalogs

catalogExists, createCatalog, dropCatalog

Method Detail

listCatalogs

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

List all the catalogs under this metalake.

Specified by:

listCatalogs in interface SupportsCatalogs

Returns:

A list of the catalog names under the current metalake.

Throws:

NoSuchMetalakeException - If the metalake does not exist.

listCatalogsInfo

public Catalog[] listCatalogsInfo()
                           throws NoSuchMetalakeException

List all the catalogs with their information under this metalake.

Specified by:

listCatalogsInfo in interface SupportsCatalogs

Returns:

A list of Catalog under the specified namespace.

Throws:

NoSuchMetalakeException - if the metalake with specified namespace does not exist.

loadCatalog

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

Load the catalog with specified identifier.

Specified by:

loadCatalog in interface SupportsCatalogs

Parameters:

catalogName - The identifier of the catalog to load.

Returns:

The Catalog with specified identifier.

Throws:

NoSuchCatalogException - if the catalog with specified identifier 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

Create a new catalog with specified identifier, type, comment and properties.

Specified by:

createCatalog in interface SupportsCatalogs

Parameters:

catalogName - The identifier 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 with specified namespace does not exist.

CatalogAlreadyExistsException - if the catalog with specified identifier already exists.

alterCatalog

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

Alter the catalog with specified identifier by applying the changes.

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 with specified identifier does not exist.

java.lang.IllegalArgumentException - if the changes are invalid.

dropCatalog

public boolean dropCatalog(java.lang.String catalogName,
                           boolean force)
                    throws NonEmptyEntityException,
                           CatalogInUseException

Drop a catalog with specified name. If the force flag is true, it will:

• Cascade drop all sub-entities (schemas, tables, etc.) of the catalog in Gravitino store.
• Drop the catalog even if it is in use.
• External resources (e.g. database, table, etc.) associated with sub-entities will not be dropped unless it is managed (such as managed fileset).

Specified by:

dropCatalog in interface SupportsCatalogs

Parameters:

catalogName - The identifier of the catalog.

force - Whether to force the drop.

Returns:

True if the catalog was dropped, false if the catalog does not exist.

Throws:

NonEmptyEntityException - If the catalog is not empty and force is false.

CatalogInUseException - If the catalog is in use and force is false.

enableCatalog

public void enableCatalog(java.lang.String catalogName)
                   throws NoSuchCatalogException

Description copied from interface: SupportsCatalogs

Enable a catalog. If the catalog is already enabled, this method does nothing.

Specified by:

enableCatalog in interface SupportsCatalogs

Parameters:

catalogName - The identifier of the catalog.

Throws:

NoSuchCatalogException - If the catalog does not exist.

disableCatalog

public void disableCatalog(java.lang.String catalogName)
                    throws NoSuchCatalogException

Description copied from interface: SupportsCatalogs

Disable a catalog. If the catalog is already disabled, this method does nothing. Once a catalog is disabled:

• It can only be listed, loaded, dropped, or disable.
• Any other operations on the catalog will throw an CatalogNotInUseException.
• Any operation on the sub-entities (schemas, tables, etc.) will throw an CatalogNotInUseException.

Specified by:

disableCatalog in interface SupportsCatalogs

Parameters:

catalogName - The identifier of the catalog.

Throws:

NoSuchCatalogException - If the catalog does not exist.

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.

supportsRoles

public SupportsRoles supportsRoles()

Specified by:

supportsRoles in interface Metalake

Returns:

the SupportsRoles if the metalake supports role operations.

listTags

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

List all the tag names under a metalake.

Specified by:

listTags in interface TagOperations

Returns:

A list of the tag names under the current metalake.

Throws:

NoSuchMetalakeException - If the metalake does not exist.

listTagsInfo

public Tag[] listTagsInfo()
                   throws NoSuchMetalakeException

List all the tags with detailed information under the current metalake.

Specified by:

listTagsInfo in interface TagOperations

Returns:

A list of Tag under the current metalake.

Throws:

NoSuchMetalakeException - If the metalake does not exist.

getTag

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

Get a tag by its name under the current 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

Create a tag under the current 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

Alter a tag under the current 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)

Delete a tag under the current 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.

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()
                 throws NoSuchMetalakeException

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()
                                 throws NoSuchMetalakeException

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

Lists 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

Lists the group names

Returns:

The Group Name 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,
                       IllegalMetadataObjectException

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.

IllegalMetadataObjectException - If the securable object is invalid

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

listRoleNames

public java.lang.String[] listRoleNames()

Lists the role names.

Returns:

The role name list.

Throws:

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

grantRolesToUser

public User grantRolesToUser(java.util.List<java.lang.String> roles,
                             java.lang.String user)
                      throws NoSuchUserException,
                             IllegalRoleException,
                             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.

IllegalRoleException - If the Role with the given name is invalid.

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.

IllegalRoleException - If the Role with the given name is invalid.

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

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

NoSuchRoleException

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.

IllegalRoleException - If the Role with the given name is invalid.

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

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

NoSuchRoleException

revokeRolesFromGroup

public Group revokeRolesFromGroup(java.util.List<java.lang.String> roles,
                                  java.lang.String group)
                           throws NoSuchGroupException,
                                  IllegalRoleException,
                                  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.

IllegalRoleException - If the Role with the given name is invalid.

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

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

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 privileges to a role encounters storage issues.

grantPrivilegesToRole

public Role grantPrivilegesToRole(java.lang.String role,
                                  MetadataObject object,
                                  java.util.Set<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 privileges to a role encounters storage issues.

revokePrivilegesFromRole

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

Deprecated.

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.

revokePrivilegesFromRole

public Role revokePrivilegesFromRole(java.lang.String role,
                                     MetadataObject object,
                                     java.util.Set<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.

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.

listBindingRoleNames

public java.lang.String[] listBindingRoleNames()

Description copied from interface: SupportsRoles

List all the role names associated with this metadata object.

Specified by:

listBindingRoleNames in interface SupportsRoles

Returns:

The role name list associated with this metadata object.

equals

public boolean equals(java.lang.Object o)

Overrides:

equals in class MetalakeDTO

builder

public static org.apache.gravitino.client.GravitinoMetalake.Builder builder()

Returns:

the builder for creating a new instance of GravitinoMetaLake.