Dependency syntax in EiffelArtifactCreatedEvent

README.md

@@ -14,6 +14,7 @@ __IMPORTANT NOTICE:__ The contents of this repository currectly reflect a __DRAF
    1. [Event Structure](./eiffel-syntax-and-usage/event-structure.md)
    1. [The Meta Object](./eiffel-syntax-and-usage/the-meta-object.md)
    1. [The Links Object](./eiffel-syntax-and-usage/the-links-object.md)
+   1. [Compositions and Validity Checking](./eiffel-syntax-and-usage/compositions-and-validity-checking.md)
 1. The Eiffel Vocabulary
    1. [EiffelActivityTriggeredEvent](./eiffel-vocabulary/EiffelActivityTriggeredEvent.md)
    1. [EiffelActivityCanceledEvent](./eiffel-vocabulary/EiffelActivityCanceledEvent.md)

eiffel-syntax-and-usage/compositions-and-validity-checking.md

@@ -0,0 +1,37 @@
+# Compositions and validity checking
+A central concept in Eiffel is that of _compositions_. A composition represents a set of source, artifact and documentation items defined by [EiffelCompositionDefinedEvent](../eiffel-vocabulary/EiffelCompositionDefinedEvent.md) for some purpose, e.g. forming an execution environment, defining the contents of a delivery or instructing the integration of a system. Compositions may be very simple, consisting of a single item, or very large, containing any number of items in nested composition structures.
+
+## Composition Validity
+Using the __data.dependsOn__, __data.implements__ and __data.requiresImplementation__ members of [EiffelArtifactCreatedEvent](../eiffel-vocabulary/EiffelArtifactCreatedEvent.md) the validity of any given composition can be checked.
+
+### Checking Dependencies
+In this straight forward example, the integration of a system requires the presence of an interface and a third party library. Consider the following composition:
+
+![alt text](./composition-dependency-check-example.png "Dependency Checking Example")
+
+Here composition C2 is legal, but C1 is not. The reason is that B1 requires version "[1.1.0,)" of com.example:a (that is, version 1.1.0 or later). In composition C1 there is no such artifact, but in composition C2 there is.
+
+### Checking Backend Implementation Validity
+In this example we imagine a microservice setup. The service interface I has no implementation itself - instead it requires one or more implementations to which it can forward requests. There are multiple versions of the interface included, affording clients backwards compatibility.
+
+![alt text](./composition-backend-implementation-example.png "Backend Implementation Validity Example")
+
+Composition C1 is not valid: it contains two instances of A, one of I1 and one of I2. A implements I from version 1.0.0 up to, but not including, 2.0.0. Hence, I2 is lacking implementation is this composition.
+
+Composition C2, on the other hand, is valid. It also contains two instances of A, but also one instance of B, which implements I from version 1.0.0 up to 3.0.0. Consequently, in this composition I1 has three artifacts implementing it, while I2 has one.
+
+### GAV vs event links
+Wherever feasible, the Eiffel framework promotes the usage of event references to link to other artifacts. It may seem like a reasonable option to use event links to declare dependencies, as well.
+
+The pragmatic reason for using GAVs in this particular case is version ranges: with event links there is no practical way of declaring ranges.
+
+There is also a conceptual reason why event links are not suitable, however. Event links are consistently used to reference historical engineering artifacts - things that have been created and exist. Dependency declarations - particularly dependencies on version ranges - are much more intangible in nature. They do not simply provide a description of something that ought to be present. For this reason they can not be used as trace links, and are unsuitable for event reference representation.
+
+### Additional Notes
+_Isn't this a reinvention of the wheel?_ you may ask. After all, there are plenty of tools that excel in handling dependency graphs. This is true, and the Eiffel dependency definition syntax is heavily influenced not least by [Maven](http://maven.apache.org). Eiffel operates at a highly technology and context agnostic level of abstraction, however, covering e.g. projects with highly diversified technology stacks and/or projects near or crossing over into hardware. This has both limitations and benefits. An Eiffel composition check can never guarantee that a given composition will work; what it can tell you is whether it is obviously broken.
+
+It should also be noted that Eiffel's dependency syntax is opinionated. An interface requiring supporting implementation does not dictate that it requires any particular implementation (actually it can - simply use __data.dependsOn__). Rather, it is up to that implementation to declare that it supports the interface. This is in order to encourage separation of concerns and decoupling.
+
+Furthermore, Eiffel's dependency syntax makes no distinction between e.g. build time and runtime dependencies. This is for two reasons. First, it is not intended for low level dependency management: most programming languages have dedicated and specialized tools that will handle this type of dependency management. Instead, where Eiffel's comes into play is in tracking and validating large, sprawling systems of heterogeneous artifacts. Second, even if one attempts to develop specific syntax each type of dependency there will always be corner use cases which are not covered: better then to err on the side of abstraction, rather than implicitly ruling out use cases by being overly specific. That being said, it is also generally the case that an artifact has a fair idea of its intended use - it is rare that one and the same artifact is both a deployable service and a source code library, with the need to declare a unique set of dependencies for each case. Hence, the EiffelArtifactCreatedEvent dependency declarations shall be read in context.
+
+

eiffel-vocabulary/EiffelArtifactCreatedEvent.md

@@ -42,5 +42,58 @@ __Type:__ String
 __Required:__ No  
 __Description:__ The command used to build the artifact within the identified environment. Used for reproducability purposes.
 
+### data.requiresImplementation
+__Type:__ String  
+__Required:__ No  
+__Legal values:__ NONE, ANY, EXACTLY_ONE, AT_LEAST_ONE  
+__Description:__ Defines whether this artifact requires an implementing artifact. This is typically used for interfaces requiring some backend implementation, although the interface does not presume to define _which_ implementation. Implicitly interpreted as "ANY" if undefined.  
+NONE signifies that there SHALL no implementations of this artifact. In other words, a composition containing another artifact identifying it in __data.implements__ would be illegal.  
+ANY signifies that there may or may not be implementations of this artifact.  
+EXACTLY_ONE signifies that a legal composition must contain one and only one implementation of this artifact.  
+AT_LEAST_ONE signifies that a legal composition must contain one or more implementations of this artifact.
+
+### data.implements
+__Type:__ Object[]  
+__Required:__ No  
+__Description:__ An array of [GAVs](https://maven.apache.org/guides/mini/guide-naming-conventions.html) this artifact implements. The typical use case of this is to identify interfaces implemented by this artifact.
+
+#### data.implements.groupId
+__Type:__ String  
+__Required:__ Yes  
+__Description:__ The groupId of the implemented artifact.
+
+#### data.implements.artifactId
+__Type:__ String  
+__Required:__ Yes  
+__Description:__ The artifactId of the implemented artifact.
+
+#### data.implements.version
+__Type:__ String  
+__Required:__ Yes  
+__Description:__ The version of the implemented artifact. Note that [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) is supported.
+
+### data.dependsOn
+__Type:__ Object[]  
+__Required:__ No  
+__Description:__ An array of [GAVs](https://maven.apache.org/guides/mini/guide-naming-conventions.html) this artifact depends on.
+
+#### data.dependsOn.groupId
+__Type:__ String  
+__Required:__ Yes  
+__Description:__ The groupId of the dependency.
+
+#### data.dependsOn.artifactId
+__Type:__ String  
+__Required:__ Yes  
+__Description:__ The artifactId of the dependency.
+
+#### data.dependsOn.version
+__Type:__ String  
+__Required:__ Yes  
+__Description:__ The version of the dependency. Note that [version range notation](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm#MAVEN402) is supported.
+
 ## Examples
-* [Simple example](../examples/events/EiffelArtifactCreatedEvent/simple.json)
+* [Simple example](../examples/events/EiffelArtifactCreatedEvent/simple.json)
+* [Interface example](../examples/events/EiffelArtifactCreatedEvent/interface.json)
+* [Backend example](../examples/events/EiffelArtifactCreatedEvent/backend.json)
+* [Dependent example](../examples/events/EiffelArtifactCreatedEvent/dependent.json)

examples/events/EiffelArtifactCreatedEvent/backend.json

@@ -0,0 +1,50 @@
+{
+  "meta": {
+    "type": "EiffelArtifactCreatedEvent",
+    "version": "1.0",
+    "time": 1234567890,
+    "source": {
+      "domainId": "example.domain"
+    },
+    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0"
+  },
+  "data": {
+    "gav": {
+      "groupId": "com.mycompany.myproduct",
+      "artifactId": "my-backend",
+      "version": "1.0.4"
+    },
+    "fileInformation": [
+      {
+        "classifier": "",
+        "extension": "jar"
+      }
+    ],
+    "buildCommand": "/my/build/command with arguments",
+    "implements": [
+      {
+        "groupId": "com.mycompany.myproduct",
+        "artifactId": "my-interface",
+        "version": "[1.0,2.0)"
+      }
+    ]
+  },
+  "links": [
+    {
+      "type": "CAUSE",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee1"
+    },
+    {
+      "type": "PREVIOUS_VERSION",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee2"
+    },
+    {
+      "type": "COMPOSITION",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee1"
+    },
+    {
+      "type": "ENVIRONMENT",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee3"
+    }
+  ]
+}

examples/events/EiffelArtifactCreatedEvent/dependent.json

@@ -0,0 +1,50 @@
+{
+  "meta": {
+    "type": "EiffelArtifactCreatedEvent",
+    "version": "1.0",
+    "time": 1234567890,
+    "source": {
+      "domainId": "example.domain"
+    },
+    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0"
+  },
+  "data": {
+    "gav": {
+      "groupId": "com.mycompany.myproduct",
+      "artifactId": "my-dependent",
+      "version": "1.0.4"
+    },
+    "fileInformation": [
+      {
+        "classifier": "",
+        "extension": "jar"
+      }
+    ],
+    "buildCommand": "/my/build/command with arguments",
+    "dependsOn": [
+      {
+        "groupId": "com.mycompany.myproduct",
+        "artifactId": "my-interface",
+        "version": "[1.0,2.0)"
+      }
+    ]
+  },
+  "links": [
+    {
+      "type": "CAUSE",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee1"
+    },
+    {
+      "type": "PREVIOUS_VERSION",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee2"
+    },
+    {
+      "type": "COMPOSITION",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee1"
+    },
+    {
+      "type": "ENVIRONMENT",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee3"
+    }
+  ]
+}

examples/events/EiffelArtifactCreatedEvent/interface.json

@@ -0,0 +1,44 @@
+{
+  "meta": {
+    "type": "EiffelArtifactCreatedEvent",
+    "version": "1.0",
+    "time": 1234567890,
+    "source": {
+      "domainId": "example.domain"
+    },
+    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee0"
+  },
+  "data": {
+    "gav": {
+      "groupId": "com.mycompany.myproduct",
+      "artifactId": "my-interface",
+      "version": "1.0.4"
+    },
+    "fileInformation": [
+      {
+        "classifier": "",
+        "extension": "jar"
+      }
+    ],
+    "buildCommand": "/my/build/command with arguments",
+    "requiresImplementation": "AT_LEAST_ONE"
+  },
+  "links": [
+    {
+      "type": "CAUSE",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee1"
+    },
+    {
+      "type": "PREVIOUS_VERSION",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee2"
+    },
+    {
+      "type": "COMPOSITION",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee1"
+    },
+    {
+      "type": "ENVIRONMENT",
+      "target": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee3"
+    }
+  ]
+}

schemas/EiffelArtifactCreatedEvent.json

@@ -119,6 +119,61 @@
         "buildCommand": {
           "type": "string"
         },
+        "requiresImplementation": {
+          "type": "string",
+          "enum": [
+            "NONE",
+            "ANY", 
+            "EXACTLY_ONE", 
+            "AT_LEAST_ONE"
+          ]
+        },
+        "dependsOn": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "groupId": {
+                "type": "string"
+              },
+              "artifactId": {
+                "type": "string"
+              },
+              "version": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "groupId",
+              "artifactId",
+              "version"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "implements": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "groupId": {
+                "type": "string"
+              },
+              "artifactId": {
+                "type": "string"
+              },
+              "version": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "groupId",
+              "artifactId",
+              "version"
+            ],
+            "additionalProperties": false
+          }
+        },
         "customData": {
           "type": "array",
           "items": {