GH-18 - Abstractions to express CQRS concepts.

We no provide annotations to express CQRS concepts like commands, command handlers, dispatchers and query models in application code. See the Javadoc of the introduced annotations for details.

Also @domainevent was extended to carry new, optional attributes for symmetry with what's available for commands.

Author: StephanPirnbaum

jmolecules-architecture/jmolecules-cqrs-architecture/pom.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+		 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+
+	<modelVersion>4.0.0</modelVersion>
+
+	<parent>
+		<artifactId>jmolecules-architecture</artifactId>
+		<groupId>org.jmolecules</groupId>
+		<version>1.1.0-SNAPSHOT</version>
+	</parent>
+
+	<artifactId>jmolecules-cqrs-architecture</artifactId>
+
+	<name>jMolecules - CQRS Architecture</name>
+	<description>Concepts of the cqrs architecture style.</description>
+
+</project>

jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/org/jmolecules/architecture/cqrs/annotation/Command.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2020-2021 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.jmolecules.architecture.cqrs.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Identifies a command in the context of CQRS, i.e. a request to the system for the change of data. Commands are always
+ * in imperative tense and thus, unlike an event, do not state that something has already happened, but something is
+ * requested to happen. With that, the {@link CommandHandler} which is processing the command has the option reject the
+ * command.
+ *
+ * @author Christian Stettler
+ * @author Henning Schwentner
+ * @author Stephan Pirnbaum
+ * @author Martin Schimak
+ * @author Oliver Drotbohm
+ * @since 1.1
+ * @see <a href="http://cqrs.files.wordpress.com/2010/11/cqrs_documents.pdf">CQRS Documents by Greg Young - Commands</a>
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface Command {
+
+	/**
+	 * An identifier for the namespace of the command to group multiple commands and let clients express their interest in
+	 * all commands of a specific namespace. If not set, external tooling may default this to the fully-qualified package
+	 * name of the annotated type.
+	 */
+	String namespace() default "";
+
+	/**
+	 * An identifier for the name of the command used to abstract away from the type system and to guard against
+	 * refactorings. If not set, external tooling may default this to the simple class name of the annotated type.
+	 */
+	String name() default "";
+}

jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/org/jmolecules/architecture/cqrs/annotation/CommandDispatcher.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2020-2021 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.jmolecules.architecture.cqrs.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Identifies a command dispatcher in the context of CQRS, i.e. logic to dispatch a {@link Command}.
+ *
+ * @author Christian Stettler
+ * @author Henning Schwentner
+ * @author Stephan Pirnbaum
+ * @author Martin Schimak
+ * @author Oliver Drotbohm
+ * @since 1.1
+ * @see <a href="http://cqrs.files.wordpress.com/2010/11/cqrs_documents.pdf">CQRS Documents by Greg Young - Commands</a>
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+public @interface CommandDispatcher {
+
+	/**
+	 * Optional identification of the command dispatched by this dispatcher. This information may be used for easier
+	 * linkage between command and dispatcher by external tools and refers to the combination of
+	 * {@link Command#namespace()} and {@link Command#name()}, separated by '.' (dot).
+	 */
+	String dispatches() default "";
+}

jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/org/jmolecules/architecture/cqrs/annotation/CommandHandler.java

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2020-2021 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.jmolecules.architecture.cqrs.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Identifies a command handler in the context of CQRS, i.e. logic to process a {@link Command}. The command handler may
+ * or may not reject the command. In case of processing, the handler takes care of orchestrating the business logic
+ * related to the command.
+ *
+ * @author Christian Stettler
+ * @author Henning Schwentner
+ * @author Stephan Pirnbaum
+ * @author Martin Schimak
+ * @author Oliver Drotbohm
+ * @since 1.1
+ * @see <a href="http://cqrs.files.wordpress.com/2010/11/cqrs_documents.pdf">CQRS Documents by Greg Young - Commands</a>
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+public @interface CommandHandler {
+
+	/**
+	 * Optional identification of the namespace of the command handled by this handler. This information may be used for
+	 * easier linkage between command and handler by external tools and refers to {@link Command#namespace()}. When
+	 * leaving the default value, it is assumed that the method signature makes clear what command is consumed. If the
+	 * handler takes care of all commands of a specific namespace, the value of this field needs to be set to the
+	 * respective namespace and the {@link CommandHandler#name()} ()} needs to be set accordingly. If the handler doesn't
+	 * care about the namespace, the value may be set to the '*' (asterisk) placeholder.
+	 */
+	String namespace() default "";
+
+	/**
+	 * Optional identification of the name of the command handled by this handler. This information may be used for easier
+	 * linkage between command and handler by external tools and refers to {@link Command#name()}. When leaving the
+	 * default value, it is assumed that the method signature makes clear what command is consumed. If the handler takes
+	 * care of all commands of a specific namespace, the value of this field needs to be set to the '*' (asterisk)
+	 * placeholder.
+	 */
+	String name() default "";
+
+}

jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/org/jmolecules/architecture/cqrs/annotation/QueryModel.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2020-2021 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.jmolecules.architecture.cqrs.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Identifies a query model element in the context of CQRS, i.e. a (persistent) object optimized for read-access and
+ * only only on the Q(uery) part of the architecture. The query model represents the current state or rather
+ * materialized view after replaying the events published by the application.
+ *
+ * @author Christian Stettler
+ * @author Henning Schwentner
+ * @author Stephan Pirnbaum
+ * @author Martin Schimak
+ * @author Oliver Drotbohm
+ * @since 1.1
+ * @see <a href="http://cqrs.files.wordpress.com/2010/11/cqrs_documents.pdf">CQRS Documents by Greg Young</a>
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+public @interface QueryModel {}

jmolecules-architecture/pom.xml

@@ -16,6 +16,7 @@
 	<description>Architectural Styles in Java</description>
 
 	<modules>
+		<module>jmolecules-cqrs-architecture</module>
 		<module>jmolecules-layered-architecture</module>
 		<module>jmolecules-onion-architecture</module>
 	</modules>

jmolecules-events/src/main/java/org/jmolecules/event/annotation/DomainEvent.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020 the original author or authors.
+ * Copyright 2020-2021 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -15,6 +15,12 @@
  */
 package org.jmolecules.event.annotation;
 
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
 /**
  * A domain event is a full-fledged part of the domain model, a representation of something that happened in the domain.
  * It allows making the events that the domain experts want to track or be notified of explicit, or which are associated
@@ -28,5 +34,25 @@
  * @see <a href="https://domainlanguage.com/wp-content/uploads/2016/05/DDD_Reference_2015-03.pdf">Domain-Driven Design
  *      Reference (Evans) - Domain Events</a>
  */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.TYPE)
+@Documented
 public @interface DomainEvent {
+
+	/**
+	 * An identifier for the namespace of the event to group multiple events and let clients express their interest in all
+	 * events of a specific namespace. If not set, external tooling may default this to the fully-qualified package name
+	 * of the annotated type.
+	 *
+	 * @since 1.1
+	 */
+	String namespace() default "";
+
+	/**
+	 * An identifier for the name of the event used to abstract away from the type system and to guard against
+	 * refactorings. If not set, external tooling may default this to the simple class name of the annotated type.
+	 *
+	 * @since 1.1
+	 */
+	String name() default "";
 }

jmolecules-events/src/main/java/org/jmolecules/event/annotation/DomainEventHandler.java

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2020-2021 the original author or authors.
+ *
+ * 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
+ *
+ *      https://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.jmolecules.event.annotation;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Identifies a domain event handler, i.e. logic to process a {@link DomainEvent}.
+ *
+ * @author Christian Stettler
+ * @author Henning Schwentner
+ * @author Stephan Pirnbaum
+ * @author Martin Schimak
+ * @author Oliver Drotbohm
+ * @since 1.1
+ */
+@Documented
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+public @interface DomainEventHandler {
+
+	/**
+	 * Optional identification of the namespace of the domain event handled by this handler. This information may be used
+	 * for easier linkage between event and handler by external tools and refers to {@link DomainEvent#namespace()}. When
+	 * leaving the default value, it is assumed that the method signature makes clear what event is consumed. If the
+	 * handler takes care of all events of a specific namespace, the value of this field needs to be set to the respective
+	 * namespace and the {@link DomainEventHandler#name()} needs to be set accordingly. If the handler doesn't care about
+	 * the namespace, the value may be set to the '*' (asterisk) placeholder.
+	 */
+	String namespace() default "";
+
+	/**
+	 * Optional identification of the name of the domain event handled by this handler. This information may be used for
+	 * easier linkage between event and handler by external tools and refers to {@link DomainEvent#name()}. When leaving
+	 * the default value, it is assumed that the method signature makes clear what event is consumed. If the handler takes
+	 * care of all events of a specific namespace, the value of this field needs to be set to the '*' asterisk
+	 * placeholder.
+	 */
+	String name() default "";
+}