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
@NonNull RealmDefinition	create(@NonNull String realmId)	Creates a new realm in created status with the given realm ID.
void	delete(@NonNull RealmDefinition expected)	Deletes the given realm.
@NonNull Optional<RealmDefinition>	get(@NonNull String realmId)	Retrieve a realm definition by realm ID.
@NonNull Stream<RealmDefinition>	list()	Returns a stream of all realm definitions.
@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.

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

@MustBeClosed
@NonNull 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