- sketch javadocs for main user interfaces

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,

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 <T> The type of the aggregate, which must implement the Aggregate interface.
+ * @param <E> The type of the event, which must implement the Event interface.
+ */
 public interface Aggregator<T extends Aggregate, E extends Event> {
 
+  /**
+   * 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) {
     );
   }
 
-
 }
+

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 <T> The type of the aggregate, which must implement the Aggregate interface.
+ * @param <C> The type of the command, which must implement the Command interface.
+ */
 public interface Behaviour<T extends Aggregate, C extends Command> {
+
+  /**
+   * 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<Event> process(T state, C command);
+
 }

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<? extends Aggregate> 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<String> fileConfigurations() {
     return Collections.emptyList();
   }

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<String> 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();
   }
 
-
 }

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<String> 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
 
 }
+

es4j-core/src/main/java/io/es4j/launcher/Es4jMain.java

@@ -67,11 +67,9 @@ public void afterRestore(Context<? extends Resource> context) throws Exception {
 
   @Override
   public void start(final Promise<Void> 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();