AxonFramework · jangalinski · Dec 31, 2023 · Jan 14, 2024 · Jan 14, 2024 · Feb 11, 2024
@@ -0,0 +1,109 @@
+# Axon Framework - Kotlin Extension
+[![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.axonframework.extensions.kotlin/axon-kotlin/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.axonframework.extensions.kotlin/axon-kotlin)
+![Build Status](https://github.com/AxonFramework/extension-kotlin/workflows/Kotlin%20Extension/badge.svg?branch=master)
+[![SonarCloud Status](https://sonarcloud.io/api/project_badges/measure?project=AxonFramework_extension-kotlin&metric=alert_status)](https://sonarcloud.io/dashboard?id=AxonFramework_extension-kotlin)
+[![Open Source Helpers](https://www.codetriage.com/axonframework/extension-kotlin/badges/users.svg)](https://www.codetriage.com/axonframework/extension-kotlin)
+
+_Note:_ This extension is still in an experimental stage.
+
+Axon Framework is a framework for building evolutionary, event-driven microservice systems,
+ based on the principles of Domain Driven Design, Command-Query Responsibility Segregation (CQRS) and Event Sourcing.
+
+As such it provides you the necessary building blocks to follow these principles.
+Building blocks like Aggregate factories and Repositories, Command, Event and Query Buses and an Event Store.
+The framework provides sensible defaults for all of these components out of the box.
+
+This set up helps you create a well-structured application without having to bother with the infrastructure.
+The main focus can thus become your business functionality.
+
+This repository provides an extension to the Axon Framework: Kotlin. It provides functionality to leverage Kotlin features to be used with Axon Framework.
+
+For more information on anything Axon, please visit our website, [http://axoniq.io](http://axoniq.io).
+
+## Getting started
+
+### Dependencies
+
+For the Kotlin extension itself you can get the version from the [axon-bom](https://github.com/AxonFramework/axon-bom) or use the following coordinates:
+
+**Maven**
+
+```
+<dependency>
+    <groupId>org.axonframework.extensions.kotlin</groupId>
+    <artifactId>axon-kotlin</artifactId>
+    <version>4.6.0</version>
+</dependency>
+```
+
+**Gradle**
+
+```
+implementation("org.axonframework.extensions.kotlin:axon-kotlin:4.6.0")
+```
+
+For the Kotlin testing extension itself please use the following coordinates:
+
+**Maven**
+
+```
+<dependency>
+    <groupId>org.axonframework.extensions.kotlin</groupId>
+    <artifactId>axon-kotlin-test</artifactId>
+    <version>4.6.0</version>
+</dependency>
+```
+
+**Gradle**
+
+```
+implementation("org.axonframework.extensions.kotlin:axon-kotlin-test:4.6.0")
+```
+
+
+## Receiving help
+
+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 [documentation](https://docs.axoniq.io/home/) 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).
+* There is a [forum](https://discuss.axoniq.io/) to support you in the case the reference guide did not sufficiently answer your question.
+Axon Framework and Server developers will help out on a best effort basis.
+Know that any support from contributors on posted question is very much appreciated on the forum.
+* Next to the forum we also monitor Stack Overflow for any questions which are tagged with `axon`.
+
+## Feature requests and issue reporting
+
+We use GitHub's [issue tracking system](https://github.com/AxonFramework/extension-kotlin/issues) for new feature
+request, extension enhancements and bugs.
+Prior to filing an issue, please verify that it's not already reported by someone else.
+
+When filing bugs:
+* A description of your setup and what's happening helps us figuring out what the issue might be
+* Do not forget to provide the version you're using
+* If possible, share a stack trace, using the Markdown semantic ```
+
+When filing features:
+* A description of the envisioned addition or enhancement should be provided
+* (Pseudo-)Code snippets showing what it might look like help us understand your suggestion better
+* If you have any thoughts on where to plug this into the framework, that would be very helpful too
+* Lastly, we value contributions to the framework highly. So please provide a Pull Request as well!
+
+## Building the extension
+
+If you want to build the extension locally, you need to check it out from GiHub and run the following command:
+
+    ./mvnw clean install
+
+### Producing JavaDocs and Sources archive
+
+Please execute the following command line if you are interested in producing KDoc and Source archives:
+
+    ./mvnw clean install -Pjavadoc-and-sources
+
+
+---
@@ -0,0 +1,114 @@
+/*
+ * Copyright (c) 2010-2024. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.axonframework.extensions.kotlin.messaging.responsetypes
+
+import org.axonframework.common.ReflectionUtils
+import org.axonframework.common.TypeReflectionUtils
+import org.axonframework.messaging.responsetypes.AbstractResponseType
+import org.axonframework.messaging.responsetypes.InstanceResponseType
+import org.axonframework.messaging.responsetypes.ResponseType
+import java.lang.reflect.Type
+import java.util.concurrent.Future
+
+/**
+ * A [ResponseType] implementation that will match with query handlers which return a multiple instances of the
+ * expected response type. If matching succeeds, the [ResponseType.convert] function will be called, which
+ * will cast the query handler it's response to an [Array] with element type [E].
+ *
+ * @param E The element type which will be matched against and converted to
+ * @author Gerard de Leeuw
+ * @since 4.10.0
+ * @see org.axonframework.messaging.responsetypes.MultipleInstancesResponseType
+ */
+class ArrayResponseType<E>(elementType: Class<E>) : AbstractResponseType<Array<E>>(elementType) {
+
+    companion object {
+        /**
+         * Indicates that the response matches with the [Type] while returning an iterable result.
+         *
+         * @see ResponseType.MATCH
+         *
+         * @see ResponseType.NO_MATCH
+         */
+        const val ITERABLE_MATCH = 1024
+    }
+
+    private val instanceResponseType: InstanceResponseType<E> = InstanceResponseType(elementType)
+
+    /**
+     * Match the query handler's response [Type] with this implementation's [E].
+     * Will return true in the following scenarios:
+     *
+     *  * If the response type is an [Array]
+     *  * If the response type is a [E]
+     *
+     * If there is no match at all, it will return false to indicate a non-match.
+     *
+     * @param responseType the response [Type] of the query handler which is matched against
+     * @return true for [Array] or [E] and [ResponseType.NO_MATCH] for non-matches
+     */
+    override fun matches(responseType: Type): Boolean =
+        matchRank(responseType) > NO_MATCH
+
+    /**
+     * Match the query handler's response [Type] with this implementation's [E].
+     * Will return a value greater than 0 in the following scenarios:
+     *
+     *  * [ITERABLE_MATCH]: If the response type is an [Array]
+     *  * [ResponseType.MATCH]: If the response type is a [E]
+     *
+     * If there is no match at all, it will return [ResponseType.NO_MATCH] to indicate a non-match.
+     *
+     * @param responseType the response [Type] of the query handler which is matched against
+     * @return [ITERABLE_MATCH] for [Array], [ResponseType.MATCH] for [E] and [ResponseType.NO_MATCH] for non-matches
+     */
+    override fun matchRank(responseType: Type): Int = when {
+        isMatchingArray(responseType) -> ITERABLE_MATCH
+        else -> instanceResponseType.matchRank(responseType)
+    }
+
+    /**
+     * Converts the given [response] of type [Object] into an [Array] with element type [E] from
+     * this [ResponseType] instance. Should only be called if [ResponseType.matches] returns true.
+     * Will throw an [IllegalArgumentException] if the given response
+     * is not convertible to an [Array] of the expected response type.
+     *
+     * @param response the [Object] to convert into an [Array] with element type [E]
+     * @return an [Array] with element type [E], based on the given [response]
+     */
+    override fun convert(response: Any): Array<E> {
+        val responseType: Class<*> = response.javaClass
+        if (responseType.isArray) {
+            @Suppress("UNCHECKED_CAST")
+            return response as Array<E>
+        }
+        throw IllegalArgumentException(
+            "Retrieved response [$responseType] is not convertible to an array with the expected element type [$expectedResponseType]"
+        )
+    }
+
+    @Suppress("UNCHECKED_CAST")
+    override fun responseMessagePayloadType(): Class<Array<E>> =
+        Array::class.java as Class<Array<E>>
+
+    override fun toString(): String = "ArrayResponseType[$expectedResponseType]"
+
+    private fun isMatchingArray(responseType: Type): Boolean {
+        val unwrapped = ReflectionUtils.unwrapIfType(responseType, Future::class.java)
+        val iterableType = TypeReflectionUtils.getExactSuperType(unwrapped, Array::class.java)
+        return iterableType != null && isParameterizedTypeOfExpectedType(iterableType)
+    }
+}
@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2010-2021. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.axonframework.extensions.kotlin
+
+import org.axonframework.eventsourcing.EventSourcingRepository
+
+
+/**
+ * Reified version of the static builder for event souring repository.
+ * @param T aggregate type.
+ * @return event sourcing repository builder for aggregate [T]
+ * @since 0.2.0
+ */
+inline fun <reified T : Any> eventSourcingRepositoryBuilder() = EventSourcingRepository(T::class.java)
+
+
+/**
+ * Reified version of the static builder for JPA repository.
+ * @param T aggregate type.
+ * @return Generic JPA repository builder for aggregate [T]
+ * @since 0.2.0
+ */
+inline fun <reified T : Any> genericJpaRepositoryBuilder() = GenericJpaRepository.builder(T::class.java)
@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2010-2021. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.axonframework.extensions.kotlin
+
+import org.axonframework.messaging.commandhandling.CommandMessage
+import org.axonframework.messaging.commandhandling.gateway.CommandGateway
+import org.axonframework.messaging.core.Metadata
+
+
+/**
+ * Callback-style [CommandGateway.send] with dedicated on-success and on-error functions
+ * @param command The command to send
+ * @param onError Callback to handle failed execution
+ * @param onSuccess Callback to handle successful execution
+ * @param R the type of result of the command handling
+ * @param C the type of payload of the command
+ * @see CommandGateway.send
+ * @since 0.1.0
+ */
+inline fun <reified C : Any, reified R : Any?> CommandGateway.send(
+    command: C,
+    noinline onSuccess: (commandMessage: CommandMessage, result: R, metadata: Metadata) -> Unit = { _, _, _ -> },
+    noinline onError: (commandMessage: CommandMessage, exception: Throwable, metadata: Metadata) -> Unit = { _, _, _ -> }
+): Unit = this.send(command, ResultDiscriminatorCommandCallback<C, R>(onSuccess, onError))
@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2010-2021. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.axonframework.extensions.kotlin
+
+import org.axonframework.serialization.SimpleSerializedType
+import org.axonframework.serialization.upcasting.event.IntermediateEventRepresentation
+import org.axonframework.serialization.upcasting.event.SingleEventUpcaster
+import kotlin.reflect.KClass
+
+/**
+ * Helpers for event upcaster.
+ * @since 0.1.0
+ */
+object EventUpcaster {
+    /**
+     * Creates a singleEventUpcaster for given type and revisions and calls [IntermediateEventRepresentation.upcastPayload] using the [converter].
+     */
+    fun <T : Any> singleEventUpcaster(eventType: KClass<*>,
+                                      storageType: KClass<T>,
+                                      revisions: Revisions,
+                                      converter: (T) -> T): SingleEventUpcaster = object : SingleEventUpcaster() {
+
+        override fun canUpcast(ir: IntermediateEventRepresentation): Boolean = SimpleSerializedType(eventType.qualifiedName, revisions.first) == ir.type
+
+        override fun doUpcast(ir: IntermediateEventRepresentation): IntermediateEventRepresentation =
+                ir.upcastPayload(
+                        SimpleSerializedType(eventType.qualifiedName, revisions.second),
+                        storageType.java,
+                        converter)
+    }
+}
+
+/**
+ * Tuple of oldRevision (nullable) and newRevision.
+ */
+typealias Revisions = Pair<String?, String>
@@ -0,0 +1,16 @@
+#
+# Copyright (c) 2010-2023. Axon Framework
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+restart.include.axon-kotlin=axon-kotlin-${project.version}.jar