fix: update events listeners code snipsets (#112) (#115)

Author: bercianor

docs/flamingock-library-config/events.md

@@ -32,6 +32,36 @@ Flamingock emits three types of events:
 The Success and Failure events are mutually exclusive, only one of them will be raised for a given execution.
 :::
 
+## Event Emission Order
+
+Events are emitted in a specific order during the Flamingock execution process:
+
+1. **PipelineStartedEvent**: Emitted at the beginning of the pipeline execution, after validation and lock acquisition.
+2. **StageStartedEvent**: Emitted for each stage before its execution begins.
+3. **StageCompletedEvent** or **StageFailedEvent**: Emitted when a stage finishes successfully or fails. Only one of these will be emitted per stage.
+4. **PipelineCompletedEvent** or **PipelineFailedEvent**: Emitted at the end of the pipeline execution. Only one of these will be emitted, indicating overall success or failure.
+
+If a stage fails, both StageFailedEvent and PipelineFailedEvent will be emitted. If the pipeline completes successfully, PipelineCompletedEvent is emitted after all stages have completed.
+
+## Event Scope
+
+Flamingock supports events at two levels:
+
+- **Pipeline Events**: Provide information about the entire migration process.
+- **Stage Events**: Provide granular information about individual stage executions.
+
+This allows you to monitor both high-level progress and detailed stage-by-stage execution status.
+
+## Event Data
+
+Events provide access to relevant information about the execution state:
+
+- **Started Events** (`PipelineStartedEvent`, `StageStartedEvent`): These events are simple markers with no additional data.
+- **Completed Events**:
+  - `StageCompletedEvent`: Provides access to the execution result via `getResult()`, which returns a `StageExecutor.Output` object containing the stage summary with details like the number of applied changes.
+  - `PipelineCompletedEvent`: A simple marker event with no additional data.
+- **Failed Events** (`StageFailedEvent`, `PipelineFailedEvent`): Provide access to the exception that caused the failure via `getException()`, allowing you to inspect the error details.
+
 ## Standalone basic example
 
 In the Flamingock builder, you must configure the events you intend to use and implement the corresponding listeners.
@@ -72,28 +102,22 @@ In the Flamingock builder, you must configure the events you intend to use and i
 <Tabs groupId="languages">
   <TabItem value="java" label="Java" default>
   ```java
-public class StageCompletedListener implements ApplicationListener<StageCompletedEvent> {
-
-    public static int executed = 0;
-    @Override
-    public void accept(StageCompletedEvent stageCompletedEvent) {
-        executed++;
-    }
+  public class StageCompletedListener implements Consumer<IStageCompletedEvent> {
+      @Override
+      public void accept(IStageCompletedEvent event) {
+          System.out.println("Stage execution completed with " + event.getResult().getSummary().getAppliedChangesCount() + " changes applied");
+      }
+  }
 }
   ```
   </TabItem>
   <TabItem value="kotlin" label="Kotlin">
   ```kotlin
-class StageCompletedListener : (StageCompletedEvent) -> Unit {
-
-    companion object {
-        var executed = 0
-    }
-
-    override fun invoke(stageCompletedEvent: StageCompletedEvent) {
-        executed++
-    }
-}
+   class StageCompletedListener : (IStageCompletedEvent) -> Unit {
+       override fun invoke(event: IStageCompletedEvent) {
+           println("Stage execution completed with ${event.result.summary.appliedChangesCount} changes applied")
+       }
+   }
   ```
   </TabItem>
 </Tabs>
@@ -154,7 +178,7 @@ class StageCompletedListener : (StageCompletedEvent) -> Unit {
         }
 
         @Bean
-        fun StageStartedListener(): StageStartedListener {
+        fun stageStartedListener(): StageStartedListener {
             return StageStartedListener()
         }
 
@@ -180,21 +204,21 @@ public class StageCompletedListener implements ApplicationListener<SpringStageCo
 
     public static int executed = 0;
     @Override
-    public void accept(SpringStageCompletedEvent springStageCompletedEvent) {
+    public void onApplicationEvent(SpringStageCompletedEvent springStageCompletedEvent) {
         executed++;
     }
 }
   ```
   </TabItem>
   <TabItem value="kotlin" label="Kotlin">
   ```kotlin
-class StageCompletedListener : (SpringStageCompletedEvent) -> Unit {
+class StageCompletedListener : ApplicationListener<SpringStageCompletedEvent> {
 
     companion object {
         var executed = 0
     }
 
-    override fun invoke(springStageCompletedEvent: SpringStageCompletedEvent) {
+    override fun onApplicationEvent(event: SpringStageCompletedEvent) {
         executed++
     }
 }