From 52dd96a721c7f7e7b4f3744914fc1d38d4c86dd0 Mon Sep 17 00:00:00 2001 From: Mitchell Herrijgers Date: Thu, 3 Oct 2024 17:15:18 +0100 Subject: [PATCH 1/4] MULTI-REPO_COMMIT: Move all extension reference guides to their designated page and rename README.adoc to index.adoc for friendlier URLS. Many small changes based on build output have also been done over many repositories. Some parts needed escaping, didn't have proper syntax, or headers that should really be tabs. (cherry picked from commit 822e9946384b7973bd95079305657b39aaea43d2) --- docs/README.md | 23 +++++++++++++++++++ docs/_playbook/playbook.yaml | 2 +- docs/extension-guide/antora.yml | 14 ----------- docs/reference/antora.yml | 14 +++++++++++ .../modules/ROOT/pages/consuming.adoc | 4 ++-- .../modules/ROOT/pages/index.adoc | 0 .../modules/ROOT/pages/message-format.adoc | 0 .../modules/ROOT/pages/publishing.adoc | 2 +- .../ROOT/pages/springboot-configuration.adoc | 0 .../modules/nav.adoc | 0 10 files changed, 41 insertions(+), 18 deletions(-) create mode 100644 docs/README.md delete mode 100644 docs/extension-guide/antora.yml create mode 100644 docs/reference/antora.yml rename docs/{extension-guide => reference}/modules/ROOT/pages/consuming.adoc (92%) rename docs/{extension-guide => reference}/modules/ROOT/pages/index.adoc (100%) rename docs/{extension-guide => reference}/modules/ROOT/pages/message-format.adoc (100%) rename docs/{extension-guide => reference}/modules/ROOT/pages/publishing.adoc (97%) rename docs/{extension-guide => reference}/modules/ROOT/pages/springboot-configuration.adoc (100%) rename docs/{extension-guide => reference}/modules/nav.adoc (100%) diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..43b39b1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,23 @@ +# Documentation For Axon Framework - Kafka Extension. + +This folder contains the docs related to the Kafka Extension for Axon Framework. The docs in this folder are written as part of the [AxonIQ Library](https://library.axoniq.io), and are [written in Ascii and built with Antora.](https://library.axoniq.io/contribution_guide/overview/platform.html) + +The following are the current documentation sources (folders): + +- `extension-guide` : [The Kafka Extension Guide](https://library.axoniq.io/kafka-extension-reference/index.html) + +## Contributing to the docs. + +You are welcome to contribute to these docs. Whether you want to fix a typo, or you find something missing, something that is not clear or can be improved, or even if you want to write an entire piece of docs to illustrate something that could help others to understand the use of the Bike Rental App, you are more than welcome to send a Pull Request to this GitHub repository. Just make sure you follow the guidelines explained in [AxonIQ Library Contribution Guide](https://library.axoniq.io/contribution_guide/index.html) + +## Building and testing these docs locally. + +If you want to build and explore the docs locally (because you have made changes or before contributing), you can use the Antora's build file in `docs/_playbook` folder. + +You can check the [detailed information on how the process to build the docs works](https://library.axoniq.io/contribution_guide/overview/build.html), but in short, all you have to do is: + +1. Make sure you have Node (a LTS version is preferred), Antora and Vale installed in your system. +2. CD to the `docs/_playbook` folder. +3. Run `npx antora playbook.yaml`. Antora will generate the set of static html files under `docs/_playbook/build/site` +4. Move to `docs/_playbook/build/site` and execute some local http server to serve files in that directory. For example by executing `python3 -m http.server 8070` +5. Open your browser and go to `http://localhost:8070`. You should be able to navigate the local version of the docs. diff --git a/docs/_playbook/playbook.yaml b/docs/_playbook/playbook.yaml index 276b346..bb027f3 100644 --- a/docs/_playbook/playbook.yaml +++ b/docs/_playbook/playbook.yaml @@ -1,6 +1,6 @@ site: title: Axon Kafka Extension docs PREVIEW - start_page: kafka_extension_guide::index.adoc + start_page: kafka-extension-reference::index.adoc content: sources: diff --git a/docs/extension-guide/antora.yml b/docs/extension-guide/antora.yml deleted file mode 100644 index 44e1318..0000000 --- a/docs/extension-guide/antora.yml +++ /dev/null @@ -1,14 +0,0 @@ -name: kafka_extension_guide -title: Kafka Extension Guide -version: true -prerelease: true -start_page: ROOT:index.adoc - -asciidoc: - attributes: - component_description: The Kafka Extension Guide from the former Axon Framework reference guide - type: guide - group: axon-framework - -nav: - - modules/nav.adoc \ No newline at end of file diff --git a/docs/reference/antora.yml b/docs/reference/antora.yml new file mode 100644 index 0000000..4554488 --- /dev/null +++ b/docs/reference/antora.yml @@ -0,0 +1,14 @@ +name: kafka-extension-reference +title: Kafka Extension Reference +version: true +prerelease: true +start_page: ROOT:index.adoc + +asciidoc: + attributes: + component_description: Extension adding Kafka integration for event streaming + type: extension-reference + group: axon-framework + +nav: + - modules/nav.adoc \ No newline at end of file diff --git a/docs/extension-guide/modules/ROOT/pages/consuming.adoc b/docs/reference/modules/ROOT/pages/consuming.adoc similarity index 92% rename from docs/extension-guide/modules/ROOT/pages/consuming.adoc rename to docs/reference/modules/ROOT/pages/consuming.adoc index ae4fe06..33e45c3 100644 --- a/docs/extension-guide/modules/ROOT/pages/consuming.adoc +++ b/docs/reference/modules/ROOT/pages/consuming.adoc @@ -1,7 +1,7 @@ :navtitle: Consuming Events From Kafka = Consuming Events from Kafka -Event messages in an Axon application can be consumed through either a Subscribing or a Tracking xref:axon_framework_ref:events:event-processors/README.adoc[Event Processor]. Both options are maintained when it comes to consuming events from a Kafka topic, which from a set-up perspective translates to a xref:#subscribable-message-source[SubscribableMessageSource] or a xref:#streamable-messasge-source[StreamableKafkaMessageSource] respectively, Both will be described in more detail later on, as we first shed light on the general requirements for event consumption in Axon through Kafka. +Event messages in an Axon application can be consumed through either a Subscribing or a Tracking xref:axon-framework-reference:events:event-processors/index.adoc[Event Processor]. Both options are maintained when it comes to consuming events from a Kafka topic, which from a set-up perspective translates to a xref:#subscribable-message-source[SubscribableMessageSource] or a xref:#streamable-messasge-source[StreamableKafkaMessageSource] respectively, Both will be described in more detail later on, as we first shed light on the general requirements for event consumption in Axon through Kafka. Both approaches use a similar mechanism to poll events with a Kafka `Consumer`, which breaks down to a combination of a `ConsumerFactory` and a `Fetcher`. The extension provides a `DefaultConsumerFactory`, whose sole requirement is a `Map` of configuration properties. The `Map` contains the settings to use for the Kafka `Consumer` client, such as the Kafka instance locations. Please check the link:https://kafka.apache.org/[Kafka documentation,window=_blank,role=external] for the possible settings and their values. @@ -38,7 +38,7 @@ public class KafkaEventConsumptionConfiguration { Using the `SubscribableKafkaMessageSource` means you are inclined to use a `SubscribingEventProcessor` to consume the events in your event handlers. -When using this source, Kafka's idea of pairing `Consumer` instances into "Consumer Groups" is used. This is strengthened by making the `groupId` upon source construction a _hard requirement_. To use a common `groupId` essentially means that the event-stream-workload can be shared on Kafka's terms, whereas a `SubscribingEventProcessor` typically works on its own accord regardless of the number of instances. The workload sharing can be achieved by having several application instances with the same `groupId` or by adjusting the consumer count through the `SubscribableKafkaMessageSource` builder. The same benefit holds for xref:axon_framework_ref:events:event-processors/streaming.adoc#replaying-events[resetting] an event stream, which in Axon is reserved to the `TrackingEventProcessor`, but is now opened up through Kafka's own API's. +When using this source, Kafka's idea of pairing `Consumer` instances into "Consumer Groups" is used. This is strengthened by making the `groupId` upon source construction a _hard requirement_. To use a common `groupId` essentially means that the event-stream-workload can be shared on Kafka's terms, whereas a `SubscribingEventProcessor` typically works on its own accord regardless of the number of instances. The workload sharing can be achieved by having several application instances with the same `groupId` or by adjusting the consumer count through the `SubscribableKafkaMessageSource` builder. The same benefit holds for xref:axon-framework-reference:events:event-processors/streaming.adoc#replaying-events[resetting] an event stream, which in Axon is reserved to the `TrackingEventProcessor`, but is now opened up through Kafka's own API's. Although the `SubscribableKafkaMessageSource` thus provides the niceties the tracking event processor normally provides, it does come with two catches: diff --git a/docs/extension-guide/modules/ROOT/pages/index.adoc b/docs/reference/modules/ROOT/pages/index.adoc similarity index 100% rename from docs/extension-guide/modules/ROOT/pages/index.adoc rename to docs/reference/modules/ROOT/pages/index.adoc diff --git a/docs/extension-guide/modules/ROOT/pages/message-format.adoc b/docs/reference/modules/ROOT/pages/message-format.adoc similarity index 100% rename from docs/extension-guide/modules/ROOT/pages/message-format.adoc rename to docs/reference/modules/ROOT/pages/message-format.adoc diff --git a/docs/extension-guide/modules/ROOT/pages/publishing.adoc b/docs/reference/modules/ROOT/pages/publishing.adoc similarity index 97% rename from docs/extension-guide/modules/ROOT/pages/publishing.adoc rename to docs/reference/modules/ROOT/pages/publishing.adoc index ae60bc6..9df449b 100644 --- a/docs/extension-guide/modules/ROOT/pages/publishing.adoc +++ b/docs/reference/modules/ROOT/pages/publishing.adoc @@ -3,7 +3,7 @@ When Event Messages are published to an Event Bus (or Event Store), they can be forwarded to a Kafka topic using the `KafkaPublisher`. To achieve this it will utilize a Kafka `Producer`, retrieved through Axon's `ProducerFactory`. The `KafkaPublisher` in turn receives the events to publish from a `KafkaEventPublisher`. -Since the `KafkaEventPublisher` is an event message handler in Axon terms, we can provide it to any xref:axon_framework_ref:events:event-processors/README.adoc[Event Processor] to receive the published events. The choice of event processor which brings differing characteristics for event publication to Kafka: +Since the `KafkaEventPublisher` is an event message handler in Axon terms, we can provide it to any xref:axon-framework-reference:events:event-processors/index.adoc[Event Processor] to receive the published events. The choice of event processor which brings differing characteristics for event publication to Kafka: - *Subscribing Event Processor* - publication of messages to Kafka will occur in the same thread (and Unit of Work) which published the events to the event bus. This approach ensures failure to publish to Kafka enforces failure of the initial event publication on the event bus diff --git a/docs/extension-guide/modules/ROOT/pages/springboot-configuration.adoc b/docs/reference/modules/ROOT/pages/springboot-configuration.adoc similarity index 100% rename from docs/extension-guide/modules/ROOT/pages/springboot-configuration.adoc rename to docs/reference/modules/ROOT/pages/springboot-configuration.adoc diff --git a/docs/extension-guide/modules/nav.adoc b/docs/reference/modules/nav.adoc similarity index 100% rename from docs/extension-guide/modules/nav.adoc rename to docs/reference/modules/nav.adoc From 617487df7c66b191239aa2e6d4301bb52456a802 Mon Sep 17 00:00:00 2001 From: Mitchell Herrijgers Date: Thu, 3 Oct 2024 17:06:50 +0100 Subject: [PATCH 2/4] Fix dead links over all documentation repositories (cherry picked from commit 86411f38e8d6969a8bab8a8a9a38097ef133040a) --- docs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/README.md b/docs/README.md index 43b39b1..5cd348a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # Documentation For Axon Framework - Kafka Extension. -This folder contains the docs related to the Kafka Extension for Axon Framework. The docs in this folder are written as part of the [AxonIQ Library](https://library.axoniq.io), and are [written in Ascii and built with Antora.](https://library.axoniq.io/contribution_guide/overview/platform.html) +This folder contains the docs related to the Kafka Extension for Axon Framework. The docs in this folder are written as part of the [AxonIQ Library](https://library.axoniq.io), and are [written in Ascii and built with Antora.](https://library.axoniq.io/contibution-guide/overview/platform.html) The following are the current documentation sources (folders): @@ -8,13 +8,13 @@ The following are the current documentation sources (folders): ## Contributing to the docs. -You are welcome to contribute to these docs. Whether you want to fix a typo, or you find something missing, something that is not clear or can be improved, or even if you want to write an entire piece of docs to illustrate something that could help others to understand the use of the Bike Rental App, you are more than welcome to send a Pull Request to this GitHub repository. Just make sure you follow the guidelines explained in [AxonIQ Library Contribution Guide](https://library.axoniq.io/contribution_guide/index.html) +You are welcome to contribute to these docs. Whether you want to fix a typo, or you find something missing, something that is not clear or can be improved, or even if you want to write an entire piece of docs to illustrate something that could help others to understand the use of the Bike Rental App, you are more than welcome to send a Pull Request to this GitHub repository. Just make sure you follow the guidelines explained in [AxonIQ Library Contribution Guide](https://library.axoniq.io/contibution-guide/index.html) ## Building and testing these docs locally. If you want to build and explore the docs locally (because you have made changes or before contributing), you can use the Antora's build file in `docs/_playbook` folder. -You can check the [detailed information on how the process to build the docs works](https://library.axoniq.io/contribution_guide/overview/build.html), but in short, all you have to do is: +You can check the [detailed information on how the process to build the docs works](https://library.axoniq.io/contibution-guide/overview/build.html), but in short, all you have to do is: 1. Make sure you have Node (a LTS version is preferred), Antora and Vale installed in your system. 2. CD to the `docs/_playbook` folder. From 0df0ac663561c79be82127869772b9d8bb334eaf Mon Sep 17 00:00:00 2001 From: Mitchell Herrijgers Date: Tue, 8 Oct 2024 14:43:50 +0100 Subject: [PATCH 3/4] Enable versioning and add release notes page --- docs/reference/antora.yml | 5 +++-- .../reference/modules/ROOT/pages/release-notes.adoc | 13 +++++++++++++ docs/reference/modules/nav.adoc | 3 ++- 3 files changed, 18 insertions(+), 3 deletions(-) create mode 100644 docs/reference/modules/ROOT/pages/release-notes.adoc diff --git a/docs/reference/antora.yml b/docs/reference/antora.yml index 4554488..d381aea 100644 --- a/docs/reference/antora.yml +++ b/docs/reference/antora.yml @@ -1,7 +1,8 @@ name: kafka-extension-reference title: Kafka Extension Reference -version: true -prerelease: true +version: + axon-kafka-(?+({0..9}).+({0..9})).*: $ + master: development start_page: ROOT:index.adoc asciidoc: diff --git a/docs/reference/modules/ROOT/pages/release-notes.adoc b/docs/reference/modules/ROOT/pages/release-notes.adoc new file mode 100644 index 0000000..7a4d57e --- /dev/null +++ b/docs/reference/modules/ROOT/pages/release-notes.adoc @@ -0,0 +1,13 @@ += Release Notes Kafka Extension +:navtitle: Release notes + +You can find the release notes for the Kafka Extension of version 4.10.0 below. +For earlier releases, please go to the link:https://legacydocs.axoniq.io/reference-guide/release-notes/rn-extensions/rn-kafka[legacy documentation]. + +== Release 4.10 + +. Upgrades the Kafka Extension to be compatible with Axon Framework 4.10.0 +. Updates various dependencies +. Adds the ability to ignore metadata keys + +See the link:https://github.com/AxonFramework/extension-kafka/releases/tag/axon-kafka-4.10.0[GitHub release notes] for an exhaustive list of all changes. \ No newline at end of file diff --git a/docs/reference/modules/nav.adoc b/docs/reference/modules/nav.adoc index fd8ce41..4c80e1f 100644 --- a/docs/reference/modules/nav.adoc +++ b/docs/reference/modules/nav.adoc @@ -2,4 +2,5 @@ ** xref:ROOT:publishing.adoc[] ** xref:ROOT:consuming.adoc[] ** xref:ROOT:message-format.adoc[] -** xref:ROOT:springboot-configuration.adoc[] \ No newline at end of file +** xref:ROOT:springboot-configuration.adoc[] +** xref:ROOT:release-notes.adoc[] \ No newline at end of file From 57756aedef85b762fd2b30aa2e23589e51393248 Mon Sep 17 00:00:00 2001 From: Mitchell Herrijgers Date: Tue, 8 Oct 2024 14:46:56 +0100 Subject: [PATCH 4/4] Fix references to AF reference guide in docs --- README.md | 2 +- docs/reference/modules/ROOT/pages/message-format.adoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 8ec9b92..a69cef3 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,7 @@ Are you having trouble using the extension? We'd like to help you out the best we can! There are a couple of things to consider when you're traversing anything Axon: -* Checking the [reference guide](https://library.axoniq.io/axon_framework_ref/) should be your first stop, +* Checking the [reference guide](https://library.axoniq.io/axon-framework-reference/) should be your first stop, as the majority of possible scenarios you might encounter when using Axon should be covered there. * If the Reference Guide does not cover a specific topic you would've expected, we'd appreciate if you could post a [new thread/topic on our library fourms describing the problem](https://discuss.axoniq.io/c/26). diff --git a/docs/reference/modules/ROOT/pages/message-format.adoc b/docs/reference/modules/ROOT/pages/message-format.adoc index 7aab8c0..b2cd2f7 100644 --- a/docs/reference/modules/ROOT/pages/message-format.adoc +++ b/docs/reference/modules/ROOT/pages/message-format.adoc @@ -7,11 +7,11 @@ Albeit the default, this implementation allows for some customization, such as h The `SequencingPolicy` can be adjusted to change the behaviour of the record key being used. The default sequencing policy is the `SequentialPerAggregatePolicy`, which leads to the aggregate identifier of an event being the key of a `ProducerRecord` and `ConsumerRecord`. -The format of an event message defines an API between the producer and the consumer of the message. This API may change over time, leading to incompatibility between the event class' structure on the receiving side and the event structure of a message containing the old format. Axon addresses the topic of xref:axon_framework_ref:events:event-versioning.adoc[Event Versioning] by introducing Event Upcasters. The `DefaultKafkaMessageConverter` supports this by provisioning an `EventUpcasterChain` and run the upcasting process on the `MetaData` and `Payload` of individual messages converted from `ConsumerRecord` before those are passed to the `Serializer` and converted into `Event` instances. +The format of an event message defines an API between the producer and the consumer of the message. This API may change over time, leading to incompatibility between the event class' structure on the receiving side and the event structure of a message containing the old format. Axon addresses the topic of xref:axon-framework-reference:events:event-versioning.adoc[Event Versioning] by introducing Event Upcasters. The `DefaultKafkaMessageConverter` supports this by provisioning an `EventUpcasterChain` and run the upcasting process on the `MetaData` and `Payload` of individual messages converted from `ConsumerRecord` before those are passed to the `Serializer` and converted into `Event` instances. Note that the `KafkaMessageConverter` feeds the upcasters with messages one-by-one, limiting it to one-to-one or one-to-many upcasting only. Upcasters performing a many-to-one or many-to-many operation thus won't be able to operate inside the extension (yet). -Lastly, the `Serializer` used by the converter can be adjusted. See the xref:axon_framework_ref:ROOT:serialization.adoc[Serializer] section for more details on this. +Lastly, the `Serializer` used by the converter can be adjusted. See the xref:axon-framework-reference:ROOT:serialization.adoc[Serializer] section for more details on this. [source,java] ----