Package org.apache.polaris.persistence.nosql.realms.api

Interface RealmManagement

public interface RealmManagement

Low-level realm management functionality.

Realm IDs must conform to the following constraints:

• Must not start or end with whitespaces.
• Must only consist of US-ASCII letters or digits or hyphens (-) or underscores (_).
• Must not start with two consecutive colons (::).
• Must not be empty.
• Must not be longer than 128 characters.

Note: In a CDI container RealmManagement can be directly injected.

Method Summary

Modifier and Type	Method	Description
RealmDefinition	create(String realmId)	Creates a new realm in created status with the given realm ID.
void	delete(RealmDefinition expected)	Deletes the given realm.
Optional<RealmDefinition>	get(String realmId)	Retrieve a realm definition by realm ID.
Stream<RealmDefinition>	list()	Returns a stream of all realm definitions.
RealmDefinition	update(RealmDefinition expected, RealmDefinition update)	Updates a realm definition to update, if the persisted state matches the expected state, and if the status transition is valid.

Method Details

create

@Nonnull
RealmDefinition create(@Nonnull
 String realmId)

Creates a new realm in created status with the given realm ID.

Returns:

the persisted state of the realm definition

Throws:

RealmAlreadyExistsException - if a realm with the given ID already exists

list

@Nonnull
@MustBeClosed
Stream<RealmDefinition> list()

Returns a stream of all realm definitions. The returned stream must be closed.

get

@Nonnull
Optional<RealmDefinition> get(@Nonnull
 String realmId)

Retrieve a realm definition by realm ID.

Returns:

the realm definition if it exists.

update

@Nonnull
RealmDefinition update(@Nonnull
 RealmDefinition expected,
 @Nonnull
 RealmDefinition update)

Updates a realm definition to update, if the persisted state matches the expected state, and if the status transition is valid.

Parameters:

expected - The expected persisted state of the realm definition. This must exactly represent the persisted realm definition as returned by create(String) or get(String) or a prior update(RealmDefinition, RealmDefinition).

update - the new state of the realm definition to be persisted, the created and updated attributes are solely managed by the implementation.

Returns:

the persisted state of the realm definition

Throws:

RealmNotFoundException - if a realm with the given ID does not exist

RealmExpectedStateMismatchException - if the expected state does not match

IllegalArgumentException - if the transition is not valid.

delete

void delete(@Nonnull
 RealmDefinition expected)

Deletes the given realm.

Parameters:

expected - The expected persisted state of the realm definition. This must exactly represent the persisted realm definition as returned by create(String) or get(String) or update(RealmDefinition, RealmDefinition).

Throws:

RealmNotFoundException - if a realm with the given ID does not exist

RealmExpectedStateMismatchException - if the expected state does not match