GH-152 - Introduce @stereotype meta-annotation.

We now ship an @stereotype annotation in a jstereotype artifact that allows marking annotations and types as stereotypes. An API working with that metadata will subsequently be introduced in jMolecules Integrations.

The jmolecules-ddd and jmolecules-hexagonal-architecture artifact have been fully enriched with both the annotations and the derived JSON metadata. Other artifacts have been annotated with @stereotype but not yet fully described in terms of stereotype hierarchies.

Author: odrotbohm

Diff for: etc/schemas/jmolecules-catalog.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json.schemastore.org/schema-catalog.json",
+  "version": 1,
+  "schemas": [
+    {
+      "name": "jMolecules Stereotype Groups Schema",
+      "description": "Schema to define jMolecules stereotype groups",
+      "fileMatch": [
+        "jmolecules-groups.json",
+        "**/jmolecules-groups.json",
+      ],
+      "url": "https://schemas.jmolecules.org/jmolecules-groups.schema.json"
+    },
+    {
+      "name": "jMolecules Stereotypes Schema",
+      "description": "Schema to define jMolecules stereotypes",
+      "fileMatch": [
+        "jmolecules-stereotypes.json",
+        "**/jmolecules-stereotypes.json"
+      ],
+      "url": "https://schemas.jmolecules.org/jmolecules-stereotypes.schema.json"
+    }
+  ]
+}

Diff for: etc/schemas/jmolecules-groups.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.jmolecules.org/jmolecules-groups.schema.json",
+  "type": "object",
+  "description": "Configuration for jMolecules stereotype groups",
+  "properties": {
+    "groups": {
+      "type": "array",
+      "description": "List of group definitions that stereotypes can belong to",
+      "items": {
+        "type": "object",
+        "required": ["ids", "displayName"],
+        "properties": {
+          "ids": {
+            "type": "array",
+            "description": "List of identifiers for this group",
+            "items": {
+              "type": "string",
+              "pattern": "^[\\w.-]+$",
+              "description": "Group identifier using dot notation"
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "displayName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable name for the group"
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "Processing priority of the group, defaults to 0"
+          }
+        },
+        "additionalProperties": false
+      },
+      "minItems": 1
+    }
+  },
+  "required": ["groups"],
+  "additionalProperties": false
+}

Diff for: etc/schemas/jmolecules-stereotypes.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://schemas.jmolecules.org/jmolecules-stereotypes.schema.json",
+  "type": "object",
+  "description": "Configuration for jMolecules stereotypes",
+  "properties": {
+    "stereotypes": {
+      "type": "array",
+      "description": "List of stereotype definitions that can be applied to code elements",
+      "items": {
+        "type": "object",
+        "required": ["id", "assignments"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[\\w.-]+$",
+            "description": "Unique identifier for the stereotype using dot notation"
+          },
+          "displayName": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable name for the stereotype (optional)"
+          },
+          "assignments": {
+            "type": "array",
+            "description": "List of type or annotation assignments that this stereotype can be applied to",
+            "items": {
+              "type": "string",
+              "pattern": "^@?[\\w.-]+$",
+              "description": "Type or annotation identifier, optionally prefixed with @ for annotations"
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "groups": {
+            "type": "array",
+            "description": "Groups that this stereotype belongs to",
+            "items": {
+              "type": "string",
+              "pattern": "^[\\w.-]+$",
+              "description": "Group identifier using dot notation"
+            },
+            "minItems": 1,
+            "uniqueItems": true
+          },
+          "priority": {
+            "type": "integer",
+            "minimum": 0,
+            "default": 0,
+            "description": "Processing priority of the stereotype, defaults to 0"
+          }
+        },
+        "additionalProperties": false
+      },
+      "minItems": 1
+    },
+    "groups": {
+      "$ref": "https://schemas.jmolecules.org/jmolecules-groups.schema.json#/properties/groups"
+    }
+  },
+  "required": ["stereotypes"],
+  "additionalProperties": false
+}

Diff for: jmolecules-architecture/jmolecules-cqrs-architecture/pom.xml

@@ -14,4 +14,12 @@
 	<name>jMolecules - CQRS Architecture</name>
 	<description>Concepts of the cqrs architecture style.</description>
 
+	<dependencies>
+		<dependency>
+			<groupId>org.jmolecules</groupId>
+			<artifactId>jstereotype</artifactId>
+			<version>${project.version}</version>
+		</dependency>
+	</dependencies>
+
 </project>

Diff for: jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/module-info.java

@@ -17,4 +17,6 @@
 
 	exports org.jmolecules.architecture.cqrs;
 	exports org.jmolecules.architecture.cqrs.annotation;
+
+	requires org.jmolecules.stereotype;
 }

Diff for: jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/org/jmolecules/architecture/cqrs/Command.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * 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
@@ -38,18 +40,19 @@
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
+@Stereotype
 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 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 "";
+	/**
+	 * 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 "";
 }

Diff for: jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/org/jmolecules/architecture/cqrs/CommandDispatcher.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * Identifies a command dispatcher in the context of CQRS, i.e. logic to dispatch a {@link Command}.
  *
@@ -35,6 +37,7 @@
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
+@Stereotype
 public @interface CommandDispatcher {
 
 	/**

Diff for: jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/org/jmolecules/architecture/cqrs/CommandHandler.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * 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
@@ -37,15 +39,16 @@
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE, ElementType.CONSTRUCTOR })
+@Stereotype
 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.
+	 * 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 "";
 

Diff for: jmolecules-architecture/jmolecules-cqrs-architecture/src/main/java/org/jmolecules/architecture/cqrs/QueryModel.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * 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
@@ -37,4 +39,5 @@
 @Documented
 @Retention(RetentionPolicy.RUNTIME)
 @Target(ElementType.TYPE)
+@Stereotype
 public @interface QueryModel {}

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/pom.xml

@@ -14,4 +14,14 @@
 	<name>jMolecules - Hexagonal Architecture</name>
 	<description>Concepts of the hexagonal architecture style.</description>
 
+	<dependencies>
+
+		<dependency>
+			<groupId>org.jmolecules</groupId>
+			<artifactId>jstereotype</artifactId>
+			<version>${project.version}</version>
+		</dependency>
+
+	</dependencies>
+
 </project>

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/src/main/java/module-info.java

@@ -16,4 +16,6 @@
 open module org.jmolecules.architecture.hexagonal {
 
 	exports org.jmolecules.architecture.hexagonal;
+
+	requires org.jmolecules.stereotype;
 }

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/src/main/java/org/jmolecules/architecture/hexagonal/Adapter.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * {@link Adapter}s contain technology specific implementations to either drive (see {@link PrimaryPort}) or implement
  * {@link Port}s (see {@link SecondaryPort}). Adapters must not depend on {@link Application} code other than ports.
@@ -37,6 +39,7 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.PACKAGE, ElementType.TYPE })
 @Documented
+@Stereotype(priority = 300)
 public @interface Adapter {
 
 	/**

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/src/main/java/org/jmolecules/architecture/hexagonal/Application.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * An annotation to assign packages and types the role of core application code. That code must not refer to any
  * {@link Adapter} code but only either expose or depend on functionality through {@link Port}s connecting the
@@ -36,4 +38,5 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.PACKAGE, ElementType.TYPE })
 @Documented
+@Stereotype(priority = 400)
 public @interface Application {}

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/src/main/java/org/jmolecules/architecture/hexagonal/Port.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * A {@link Port} defines an entry point into the {@link Application} that can either drive it (see {@link PrimaryPort})
  * or be driven by the application (see {@link SecondaryPort}). They are the interface with which the application
@@ -39,6 +41,7 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.PACKAGE, ElementType.TYPE })
 @Documented
+@Stereotype(priority = 300)
 public @interface Port {
 
 	/**

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/src/main/java/org/jmolecules/architecture/hexagonal/PrimaryAdapter.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * A {@link PrimaryAdapter} connects the outside of an application to an {@link PrimaryPort} exposed by the
  * application's core. For example, it could be a component accepting HTTP requests or a listener for a message broker.
@@ -35,6 +37,7 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.PACKAGE, ElementType.TYPE })
 @Documented
+@Stereotype(priority = 100)
 public @interface PrimaryAdapter {
 
 	/**

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/src/main/java/org/jmolecules/architecture/hexagonal/PrimaryPort.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * In Hexagonal Architecture an {@link PrimaryPort} describes an interface into an application's core that is exposed to
  * the outside to drive the application. A {@link PrimaryAdapter} would refer to those ports in its implementation.
@@ -35,6 +37,7 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.PACKAGE, ElementType.TYPE })
 @Documented
+@Stereotype(priority = 100)
 public @interface PrimaryPort {
 
 	/**

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/src/main/java/org/jmolecules/architecture/hexagonal/SecondaryAdapter.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * {@link SecondaryAdapter}s implement {@link SecondaryPort} to ultimately link the applications core to some extrenal
  * technology, like a database, message broker, email server or third-party service.
@@ -33,6 +35,7 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.PACKAGE, ElementType.TYPE })
 @Documented
+@Stereotype(priority = 200)
 public @interface SecondaryAdapter {
 
 	/**

Diff for: jmolecules-architecture/jmolecules-hexagonal-architecture/src/main/java/org/jmolecules/architecture/hexagonal/SecondaryPort.java

@@ -21,6 +21,8 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.jmolecules.stereotype.Stereotype;
+
 /**
  * An {@link SecondaryPort} describes abstractions that describes interfaces to the outside that are driven by the
  * application's core, like a repository (to interact with a database) or a message publisher. Usually
@@ -36,6 +38,7 @@
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ ElementType.PACKAGE, ElementType.TYPE })
 @Documented
+@Stereotype(priority = 200)
 public @interface SecondaryPort {
 
 	/**