From ed7810fb55e1bc3901925cac77cf50df424a63a0 Mon Sep 17 00:00:00 2001 From: reeferman Date: Mon, 3 Jul 2023 22:12:54 +0200 Subject: [PATCH] - sketch javadocs for main user interfaces --- .../src/main/java/io/es4j/Aggregate.java | 37 +++++++++++++++++-- .../src/main/java/io/es4j/Aggregator.java | 35 +++++++++++++++++- .../src/main/java/io/es4j/Behaviour.java | 19 ++++++++++ .../src/main/java/io/es4j/Bootstrap.java | 17 +++++++++ es4j-core/src/main/java/io/es4j/Command.java | 37 ++++++++++++++++++- es4j-core/src/main/java/io/es4j/Event.java | 26 ++++++++++++- .../main/java/io/es4j/launcher/Es4jMain.java | 2 - 7 files changed, 163 insertions(+), 10 deletions(-) diff --git a/es4j-core/src/main/java/io/es4j/Aggregate.java b/es4j-core/src/main/java/io/es4j/Aggregate.java index 7e19800..1b4e99f 100644 --- a/es4j-core/src/main/java/io/es4j/Aggregate.java +++ b/es4j-core/src/main/java/io/es4j/Aggregate.java @@ -8,18 +8,47 @@ import java.io.Serializable; -public interface Aggregate extends Shareable, Serializable { +/** + * Aggregate root in es4j. It provides an identity, tenant information, + * a schema version, and allows snapshot transformations. + * Aggregate extends Shareable and Serializable interfaces. + */ +public interface Aggregate extends Shareable, Serializable { + /** + * Retrieves the unique identifier for this aggregate. + * + * @return The unique identifier as a string for this aggregate. + */ String aggregateId(); - + /** + * Retrieves the tenant information for this aggregate. + * This method provides a default implementation and returns "default". + * + * @return The tenant as a string, default is "default". + */ default String tenant() { return "default"; } - + /** + * Retrieves the schema version of this aggregate. + * This method provides a default implementation and returns 0. + * + * @return The schema version as an integer, default is 0. + */ default int schemaVersion() { return 0; } - + /** + * Transforms the snapshot of the aggregate based on the specified schema version. + * The default implementation of this method throws an UnknownEvent exception, + * indicating that the schema version transformation is not supported. + * + * @param schemaVersion The target schema version to transform the snapshot to. + * @param snapshot The snapshot as a JsonObject that needs to be transformed. + * @return The transformed aggregate, if the transformation is supported. + * @throws UnknownEvent if the schema version transformation is not supported. + */ default Aggregate transformSnapshot(int schemaVersion, JsonObject snapshot) { throw new UnknownEvent(new Es4jError( ErrorSource.LOGIC, diff --git a/es4j-core/src/main/java/io/es4j/Aggregator.java b/es4j-core/src/main/java/io/es4j/Aggregator.java index 43585ed..a9cfd28 100644 --- a/es4j-core/src/main/java/io/es4j/Aggregator.java +++ b/es4j-core/src/main/java/io/es4j/Aggregator.java @@ -5,13 +5,46 @@ import io.es4j.core.exceptions.UnknownEvent; import io.es4j.core.objects.ErrorSource; +/** + * The Aggregator interface represents an entity responsible for + * applying events to an aggregate root and handling event version migration + * in an event sourcing based system. + * + * @param The type of the aggregate, which must implement the Aggregate interface. + * @param The type of the event, which must implement the Event interface. + */ public interface Aggregator { + /** + * Applies the given event to the provided aggregate state and returns the + * updated aggregate. + * + * @param aggregateState The current state of the aggregate. + * @param event The event to be applied to the aggregate. + * @return The updated state of the aggregate after the event has been applied. + */ T apply(T aggregateState, E event); + + /** + * Retrieves the current schema version that the aggregator is capable of processing. + * This method provides a default implementation and returns 0. + * + * @return The current schema version as an integer, default is 0. + */ default int currentSchemaVersion() { return 0; } + /** + * Transforms the event based on the specified schema version. + * The default implementation of this method throws an UnknownEvent exception, + * indicating that the event version transformation is not supported. + * + * @param schemaVersion The target schema version to transform the event to. + * @param event The event as a JsonObject that needs to be transformed. + * @return The transformed event, if the transformation is supported. + * @throws UnknownEvent if the event version transformation is not supported. + */ default E transformFrom(int schemaVersion, JsonObject event) { throw new UnknownEvent(new Es4jError( ErrorSource.LOGIC, @@ -24,5 +57,5 @@ default E transformFrom(int schemaVersion, JsonObject event) { ); } - } + diff --git a/es4j-core/src/main/java/io/es4j/Behaviour.java b/es4j-core/src/main/java/io/es4j/Behaviour.java index ebcbc50..30123ab 100644 --- a/es4j-core/src/main/java/io/es4j/Behaviour.java +++ b/es4j-core/src/main/java/io/es4j/Behaviour.java @@ -2,6 +2,25 @@ import java.util.List; +/** + * The Behaviour interface represents the behavior of an aggregate in response + * to a command. It is responsible for processing commands, validating them, and + * emitting events that should be applied to the aggregate. + * + * @param The type of the aggregate, which must implement the Aggregate interface. + * @param The type of the command, which must implement the Command interface. + */ public interface Behaviour { + + /** + * Processes the given command against the provided aggregate state. + * This involves validating the command and emitting events that represent + * the changes to be applied to the aggregate. + * + * @param state The current state of the aggregate. + * @param command The command to be processed. + * @return A list of events that should be applied to the aggregate. + */ List process(T state, C command); + } diff --git a/es4j-core/src/main/java/io/es4j/Bootstrap.java b/es4j-core/src/main/java/io/es4j/Bootstrap.java index e1a1cee..8e30ed0 100644 --- a/es4j-core/src/main/java/io/es4j/Bootstrap.java +++ b/es4j-core/src/main/java/io/es4j/Bootstrap.java @@ -3,10 +3,27 @@ import java.util.Collections; import java.util.List; +/** + * The Bootstrap interface is responsible for providing the framework + * with the necessary information regarding the aggregate roots that + * need to be taken into consideration. + */ public interface Bootstrap { + /** + * Provides the class of the aggregate root that should be taken into + * consideration by the framework. + * + * @return The class of the aggregate that extends the Aggregate interface. + */ Class aggregateClass(); + /** + * Provides file configurations that may be used for additional setup. + * This method provides a default implementation that returns an empty list. + * + * @return A list of file configurations as strings. Default is an empty list. + */ default List fileConfigurations() { return Collections.emptyList(); } diff --git a/es4j-core/src/main/java/io/es4j/Command.java b/es4j-core/src/main/java/io/es4j/Command.java index 2765870..268b699 100644 --- a/es4j-core/src/main/java/io/es4j/Command.java +++ b/es4j-core/src/main/java/io/es4j/Command.java @@ -11,24 +11,59 @@ import java.util.UUID; @JsonIgnoreProperties(ignoreUnknown = true) +/** + * The Command interface represents a command that can be issued to an aggregate. + * Commands are used to perform actions or change the state of an aggregate. + * All commands that are issued to an aggregate should implement this interface. + * Command extends Shareable and Serializable interfaces. + */ public interface Command extends Shareable, Serializable { + + /** + * Retrieves the aggregate identifier to which this command is targeted. + * + * @return The aggregate identifier as a string. + */ String aggregateId(); + /** + * Retrieves the tenant information for this command. + * This method provides a default implementation and returns "default". + * + * @return The tenant as a string, default is "default". + */ default String tenant() { return "default"; } + /** + * Generates and retrieves a unique identifier for this command. + * This method provides a default implementation that generates a random UUID. + * + * @return A unique identifier as a string. + */ default String uniqueId() { return UUID.randomUUID().toString(); } + /** + * Retrieves the list of roles required to execute this command. + * This method provides a default implementation that returns an empty list. + * + * @return A list of required roles as strings. Default is an empty list. + */ default List requiredRoles() { return Collections.emptyList(); } + /** + * Retrieves the options associated with this command. + * This method provides a default implementation that returns the default options. + * + * @return The options associated with this command, as a CommandOptions object. + */ default CommandOptions options() { return CommandOptions.defaultOptions(); } - } diff --git a/es4j-core/src/main/java/io/es4j/Event.java b/es4j-core/src/main/java/io/es4j/Event.java index bb80ce1..bb31c8a 100644 --- a/es4j-core/src/main/java/io/es4j/Event.java +++ b/es4j-core/src/main/java/io/es4j/Event.java @@ -8,17 +8,39 @@ import java.util.List; +/** + * The Event interface represents an event that is emitted from the Behaviour + * interface as a result of processing commands. It must be implemented by all events. + * Events are used to record state changes in an aggregate. Whenever the content + * of the event changes, the schema version must be incremented. + * Event extends Shareable and Serializable interfaces. + */ public interface Event extends Shareable, Serializable { + /** + * Retrieves the schema version of this event. The schema version must be + * incremented whenever the content of the event changes. + * This method provides a default implementation and returns 0. + * + * @return The schema version as an integer, default is 0. + */ default int schemaVersion() { return 0; } + /** + * Retrieves the list of tags associated with this event. + * Tags can be used for categorization or filtering of events. + * This method provides a default implementation that returns an empty list. + * + * @return A list of tags as strings. Default is an empty list. + */ default List tags() { return Collections.emptyList(); } - // todo add mandatory event-type and use that instead of the event class when storing in event log - // at startup save the map of event-type -> class + // TODO: Add mandatory event-type and use that instead of the event class when storing in event log + // At startup, save the map of event-type -> class } + diff --git a/es4j-core/src/main/java/io/es4j/launcher/Es4jMain.java b/es4j-core/src/main/java/io/es4j/launcher/Es4jMain.java index b3ddb99..cf20e4d 100644 --- a/es4j-core/src/main/java/io/es4j/launcher/Es4jMain.java +++ b/es4j-core/src/main/java/io/es4j/launcher/Es4jMain.java @@ -67,11 +67,9 @@ public void afterRestore(Context context) throws Exception { @Override public void start(final Promise startPromise) { - LOGGER.info(" ---- Starting {}::{} ---- ", this.getClass().getName(), context.deploymentID()); Infrastructure.setDroppedExceptionHandler(throwable -> LOGGER.error("[-- [Event.x] had to drop the following exception --]", throwable)); vertx.exceptionHandler(this::handleException); - this.cronTaskDeployer = new CronTaskDeployer(vertx); this.timerTaskDeployer = new TimerTaskDeployer(vertx); addEventBusInterceptors();