GITBOOK-848: No subject

Author: dgafka

.gitbook/assets/concurrent_streams.png

@@ -47,22 +47,26 @@
   * [Message Headers](modelling/extending-messaging-middlewares/message-headers.md)
   * [Interceptors (Middlewares)](modelling/extending-messaging-middlewares/interceptors.md)
 * [Event Sourcing](modelling/event-sourcing/README.md)
+  * [Installation](modelling/event-sourcing/installation.md)
   * [Event Sourcing Introduction](modelling/event-sourcing/event-sourcing-introduction/README.md)
-    * [Creating New Event Stream](modelling/event-sourcing/event-sourcing-introduction/creating-new-event-stream.md)
-    * [Applying Events](modelling/event-sourcing/event-sourcing-introduction/applying-events.md)
+    * [Working with Event Streams](modelling/event-sourcing/event-sourcing-introduction/working-with-event-streams.md)
+    * [Event Sourcing Aggregates](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/README.md)
+      * [Working with Aggregates](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/working-with-aggregates.md)
+      * [Applying Events](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/applying-events.md)
+      * [Different ways to Record Events](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/different-ways-to-record-events.md)
+      * [Making Stream immune to changes](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/making-stream-immune-to-changes.md)
+      * [Snapshoting](modelling/event-sourcing/event-sourcing-introduction/event-sourcing-aggregates/snapshoting.md)
     * [Working with Metadata](modelling/event-sourcing/event-sourcing-introduction/working-with-metadata.md)
     * [Event versioning](modelling/event-sourcing/event-sourcing-introduction/event-versioning.md)
-  * [Setting up Projections](modelling/event-sourcing/setting-up-projections/README.md)
+    * [Event Stream Persistence Strategy](modelling/event-sourcing/event-sourcing-introduction/persistence-strategy.md)
+  * [Projections Introduction](modelling/event-sourcing/setting-up-projections/README.md)
     * [Choosing Event Streams for Projection](modelling/event-sourcing/setting-up-projections/choosing-event-streams-for-projection.md)
-  * [Persistence](modelling/event-sourcing/persistence/README.md)
-    * [Persistence Strategy](modelling/event-sourcing/persistence/persistence-strategy.md)
-    * [Snapshoting](modelling/event-sourcing/persistence/snapshoting.md)
-  * [Executing and Managing](modelling/event-sourcing/executing-and-managing/README.md)
-    * [Running Projections](modelling/event-sourcing/executing-and-managing/running-projections.md)
-    * [Projection CLI Actions](modelling/event-sourcing/executing-and-managing/projection-cli-actions.md)
-    * [Access Event Store](modelling/event-sourcing/executing-and-managing/access-event-store.md)
-  * [Emitting events](modelling/event-sourcing/emitting-events.md)
-  * [Projections with State](modelling/event-sourcing/projections-with-state.md)
+    * [Executing and Managing](modelling/event-sourcing/setting-up-projections/executing-and-managing/README.md)
+      * [Running Projections](modelling/event-sourcing/setting-up-projections/executing-and-managing/running-projections.md)
+      * [Projection CLI Actions](modelling/event-sourcing/setting-up-projections/executing-and-managing/projection-cli-actions.md)
+      * [Access Event Store](modelling/event-sourcing/setting-up-projections/executing-and-managing/access-event-store.md)
+    * [Projections with State](modelling/event-sourcing/setting-up-projections/projections-with-state.md)
+    * [Emitting events](modelling/event-sourcing/setting-up-projections/emitting-events.md)
 * [Recovering, Tracing and Monitoring](modelling/recovering-tracing-and-monitoring/README.md)
   * [Resiliency](modelling/recovering-tracing-and-monitoring/resiliency/README.md)
     * [Retries](modelling/recovering-tracing-and-monitoring/resiliency/retries.md)

.gitbook/assets/event-strea.png

@@ -0,0 +1,2 @@
+# Event Sourcing Aggregates
+

.gitbook/assets/events.png

@@ -1,6 +1,6 @@
 # Applying Events
 
-As [mentioned earlier](./), Events are stored in form of a Event Stream.\
+As [mentioned earlier](../), Events are stored in form of a Event Stream.\
 Event Stream is audit of Events, which happened in the past. \
 However to protect our business invariants, we may want to work with current state of the Aggregate to know, if given action is possible or not (business invariants). 
 

.gitbook/assets/first-request.png

@@ -0,0 +1,89 @@
+# Different ways to Record Events
+
+## Two ways of setting up Event Sourced Aggregates
+
+There are two ways we can configure our Aggregate to record Events. 
+
+### 1) Pure Event Sourced Aggregate
+
+This way of handling events does allow for pure functions. This means that actions called on the Aggregate returns Events and are not changing internal state of Aggregate.
+
+```php
+#[EventSourcingAggregate] // 1
+class Ticket
+{
+    use WithAggregateVersioning; // 2
+
+    #[Identifier] // 1
+    private string $ticketId;
+    private string $ticketType;
+
+    #[CommandHandler] // 2
+    public static function register(RegisterTicket $command) : array
+    {
+        return [new TicketWasRegistered($command->getTicketId(), $command->getTicketType())];
+    }
+
+    #[CommandHandler] // 2
+    public function close(CloseTicket $command) : array
+    {
+        return [new TicketWasClosed($this->ticketId)];
+    }
+
+    #[EventSourcingHandler] // 4
+    public function applyTicketWasRegistered(TicketWasRegistered $event) : void
+    {
+        $this->ticketId       = $event->getTicketId();
+        $this->ticketType     = $event->getTicketType();
+    }
+}
+```
+
+1. `EventSourcingAggregate` and `Identifier` [works exactly the same as State-Stored Aggregate](../../../command-handling/state-stored-aggregate/).
+2. Event Sourced Aggregate must provide version. You may leave it to `Ecotone` using `WithAggregateVersioning` or you can implement it yourself.
+3. `CommandHandler`for event sourcing returns events generated by specific method. This will be passed to the [`Repository`](../../../command-handling/repository.md) to be stored. 
+4. `EventSourcingHandler` is method responsible for reconstructing `Aggregate` from previously created events. At least one event need to be handled in order to provide `Identifier`.
+
+### 2) Internal Recorder Aggregate
+
+This way of handling events allow for similarity with [State Stored Aggregates](../../../command-handling/state-stored-aggregate/).\
+This convention requires changing internal state of Aggregate to record Events. \
+Therefore Pure ES Aggregate is recommended as it's not require for any internal state changes in most of the scenarios. \
+However ES Aggregate with Internal Recorder may be useful for projects migrating with other solutions, or when our team is heavily used to working this way.
+
+```php
+#[EventSourcingAggregate] 
+class Basket
+{
+    use WithEvents; // 1
+    use WithVersioning;
+
+    #[Identifier]
+    private string $id;
+
+    #[CommandHandler] // 2
+    public static function create(CreateBasket $command) : static
+    {
+        $basket = new static();
+        $basket->recordThat(new BasketWasCreated($command->getId()));
+
+        return $basket;
+    }
+
+    #[CommandHandler] // 2
+    public function addProduct(AddProduct $command) : void
+    {
+        $this->recordThat(new ProductWasAddedToBasket($this->id, $command->getProductName()));
+    }
+
+    #[EventSourcingHandler]
+    public function applyBasketWasCreated(BasketWasCreated $basketWasCreated)
+    {
+        $this->id = $basketWasCreated->getId();
+    }
+}
+```
+
+1. In order to make use of alternative way of handling events, we need to provide trait **WithEvents**.
+2. Command Handlers instead of returning events are acting the same as [State Stored Aggregates](../../../command-handling/state-stored-aggregate/).\
+   All events which will be published using `recordThat`will be passed to the [`Repository`](../../../command-handling/repository.md) to be stored. 

.gitbook/assets/paritioned_stream.png

@@ -0,0 +1,63 @@
+# Making Stream immune to changes
+
+Changes in the Application will happen. After some time we may want to refactor namespaces, change the name of Aggregate or an Event. However those kind of changes may break our system, if we already have production data which references to any of those. \
+Therefore to make our Application to immune to future changes we need a way to decouple the code from the data in the storage, and this is what Ecotone provides.
+
+## Custom Stream Name
+
+Our Event Stream name by default is based on the Aggregate Class name. Therefore to make it immune to changes we may provide custom Stream Name. To do it we will apply `Stream` attribute to the aggregate:
+
+```php
+#[Stream("basket_stream")]
+class Basket
+```
+
+Then tell the projection to make use of it:
+
+```php
+#[Projection(self::PROJECTION_NAME, "basket_stream")]
+class BasketList
+```
+
+## Custom Aggregate Type
+
+By default events in the stream will hold Aggregate Class name as `AggregateType`. \
+You may customize this by applying `AggregateType` attribute to your Aggregate.
+
+```php
+#[AggregateType("basket")]
+class Basket
+```
+
+{% hint style="info" %}
+You may wonder what is the difference between Stream name and Aggregate Type. \
+By default the are the same, however we could use the same Stream name between different Aggregates, to store them all together within same Table. \
+\
+This may useful during migration to next version of the Aggregate, where we would want to hold both versions in same Stream.
+{% endhint %}
+
+## Storing Events By Names
+
+To avoid storing class names of Events in the `Event Store` we may mark them with name:
+
+```php
+#[NamedEvent("basket.was_created")]
+class BasketWasCreated
+{
+    public const EVENT_NAME = "basket.was_created";
+
+    private string $id;
+
+    public function __construct(string $id)
+    {
+        $this->id = $id;
+    }
+
+    public function getId(): string
+    {
+        return $this->id;
+    }
+}
+```
+
+This way Ecotone will do the mapping before storing an Event and when retrieving the Event in order to deserialize it to correct class.

.gitbook/assets/partioned_stream.png

@@ -33,7 +33,7 @@ class EventSourcingConfiguration
 2. `$thresholdTrigger` - amount of events for interval of taking a snapshot
 3. `$documentStore` - reference to document store which will be used for saving/retrieving snapshots
 
-To set up snapshots we will define [ServiceContext](../../../messaging/service-application-configuration.md) configuration.
+To set up snapshots we will define [ServiceContext](../../../../messaging/service-application-configuration.md) configuration.
 
 ```php
 #[ServiceContext]
@@ -47,7 +47,7 @@ public function aggregateSnapshots()
 ```
 
 {% hint style="info" %}
-Ecotone make use of [Document Store](../../../messaging/document-store.md) to store snapshots, by default it's enabled with event-sourcing package. \
+Ecotone make use of [Document Store](../../../../messaging/document-store.md) to store snapshots, by default it's enabled with event-sourcing package. \
 \
 If you want to clean the snapshots, you can do it manually. Snapshots are stored in `aggregate_snapshots` collection.
 {% endhint %}