awaitable-hash-map.md

AwaitableHashMap

Circumstance

• There are key-value pairs which need to organize as a hash table.
• Keys are added/removed to/from the hash table asynchronously.
• There is need to await some key is added/removed to continue asynchronous process.

Using

Usage of the AwaitableHashMap class better to describe with an example.

Imagine you are implementing a client for Docker. Creating and removing containers are heavy and time-consuming operations, so you decided to do them asynchronously. Each container has a unique name and is described with a Container class.

class Container {
    CompletableFuture<Void> start();
    CompletableFuture<Void> stop();
    CompletableFuture<CommandResult> execute(String command);
    ...
}

For convenience, you decided to track all existing containers by using the AwaitableHashMap.

var containers = new AwaitableHashMap<String, Container>();

Adding Values

As soon as a container is created and initialized, put it to the containers map.

void createContainer(String name, String image) {
    var container = new Container(name, image);
    ...
    containers.put(name, container);
}

Awaiting Values

You can interact with a container as soon as it become available. Assume, you are going to perform a shell command. To access a container simply request it by name using the await() method which returns a CompletableFuture<Container> instance. Awaiting the result you will receive the requested Container instance and be able to interact with it.

var commandResult = containers.await("my-debian")
        .thenCompose(container -> container
                .execute("echo Hello World!"));

Removing Values

As soon as a container is deleted, remove it from the containers map.

void deleteContainer(String name) {
    var container = containers.get(name);
    ...
    containers.remove(name);
}

Awaiting Removing

You can dispose some resources related with a container as soon as it is deleted. Assume, you need to delete volumes related to the container. To await deletion use the awaitRemove() method which returns a CompletableFuture<Boolean> instance. Awaiting the result you will receive the flag whether the container has actually been removed.

containers.awaitRemove(containerName)
        .thenAccept(success -> {
            if (success) {
                volumes.removeRelated(containerName);
            }
        });