Skip to content

Commit dc5ec6f

Browse files
d-stahl-ericssond-stahl-ericsson
authored
Introduced purls instead of GAVs (#195)
Replaced GAVs for meta.source.serializer in all events, and for data.identity (instead of data.gav) and data.implements and data.dependsOn in EiffelArtifactCreatedEvent. Updated schema and examples accordingly. As part of that change, replaced .gliffy files (dependent on a specific tool) with .svg files (tool agnostic) and fixed some existing issues with the images. Replaced references to GAVs in compositions-and-validity-checking.md and confidence-level-joining.md. Also a typo was fixed in compositions-and-validity-checking.md.
1 parent 530690b commit dc5ec6f

File tree

87 files changed

+7071
-1208
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

87 files changed

+7071
-1208
lines changed

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ In this straight forward example, the integration of a system requires the prese
2828

2929
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.
3030

31-
Note that the [Maven version range syntax](http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html) is used to express version ranges.
31+
Note that the [Maven version range syntax](http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html) is used to express version ranges, but that these ranges are percent encoded as the version component of the [purl identity](https://github.com/package-url/purl-spec) (although for readability, the version ranges are not percent encoded in this documentation).
3232

3333
### Checking Backend Implementation Validity
3434
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.
@@ -39,12 +39,12 @@ Composition C1 is not valid: it contains two instances of A, one of I1 and one o
3939

4040
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.
4141

42-
### GAV vs event links
42+
### Purl vs event links
4343
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.
4444

45-
The pragmatic reason for using GAVs (short for [groupId, artifactId and version](https://maven.apache.org/guides/mini/guide-naming-conventions.html)) in this particular case is version ranges: with event links there is no practical way of declaring ranges.
45+
The pragmatic reason for using (adapted) [purl identities](https://github.com/package-url/purl-spec) in this particular case is version ranges: with event links there is no practical way of declaring ranges.
4646

47-
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.
47+
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 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.
4848

4949
### Additional Notes
5050
_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.

‎eiffel-vocabulary/EiffelActivityCanceledEvent.md‎

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -106,28 +106,10 @@ __Required:__ No
106106
__Description:__ The name of the event sender.
107107

108108
#### meta.source.serializer
109-
__Type:__ Object
110-
__Format:__
111-
__Required:__ No
112-
__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
113-
114-
##### meta.source.serializer.groupId
115-
__Type:__ String
116-
__Format:__ groupId
117-
__Required:__ Yes
118-
__Description:__ The groupId of the serializer software.
119-
120-
##### meta.source.serializer.artifactId
121109
__Type:__ String
122-
__Format:__ artifactId
123-
__Required:__ Yes
124-
__Description:__ The artifactId of the serializer software.
125-
126-
##### meta.source.serializer.version
127-
__Type:__ String
128-
__Format:__ version
129-
__Required:__ Yes
130-
__Description:__ The version of the serializer software.
110+
__Format:__ [purl specification](https://github.com/package-url/purl-spec)
111+
__Required:__ No
112+
__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
131113

132114
#### meta.source.uri
133115
__Type:__ String
@@ -162,6 +144,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
162144
## Version History
163145
| Version | Introduced in | Changes |
164146
| --------- | ------------------------------------------------------ | --------------------------------------- |
147+
| 2.0.0 | Current version | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
165148
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |
166149
| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. |
167150

‎eiffel-vocabulary/EiffelActivityFinishedEvent.md‎

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -138,28 +138,10 @@ __Required:__ No
138138
__Description:__ The name of the event sender.
139139

140140
#### meta.source.serializer
141-
__Type:__ Object
142-
__Format:__
143-
__Required:__ No
144-
__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
145-
146-
##### meta.source.serializer.groupId
147-
__Type:__ String
148-
__Format:__ groupId
149-
__Required:__ Yes
150-
__Description:__ The groupId of the serializer software.
151-
152-
##### meta.source.serializer.artifactId
153141
__Type:__ String
154-
__Format:__ artifactId
155-
__Required:__ Yes
156-
__Description:__ The artifactId of the serializer software.
157-
158-
##### meta.source.serializer.version
159-
__Type:__ String
160-
__Format:__ version
161-
__Required:__ Yes
162-
__Description:__ The version of the serializer software.
142+
__Format:__ [purl specification](https://github.com/package-url/purl-spec)
143+
__Required:__ No
144+
__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
163145

164146
#### meta.source.uri
165147
__Type:__ String
@@ -194,6 +176,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
194176
## Version History
195177
| Version | Introduced in | Changes |
196178
| --------- | ------------------------------------------------------ | --------------------------------------- |
179+
| 2.0.0 | Current version | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
197180
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |
198181
| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. |
199182

‎eiffel-vocabulary/EiffelActivityStartedEvent.md‎

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -127,28 +127,10 @@ __Required:__ No
127127
__Description:__ The name of the event sender.
128128

129129
#### meta.source.serializer
130-
__Type:__ Object
131-
__Format:__
132-
__Required:__ No
133-
__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
134-
135-
##### meta.source.serializer.groupId
136-
__Type:__ String
137-
__Format:__ groupId
138-
__Required:__ Yes
139-
__Description:__ The groupId of the serializer software.
140-
141-
##### meta.source.serializer.artifactId
142130
__Type:__ String
143-
__Format:__ artifactId
144-
__Required:__ Yes
145-
__Description:__ The artifactId of the serializer software.
146-
147-
##### meta.source.serializer.version
148-
__Type:__ String
149-
__Format:__ version
150-
__Required:__ Yes
151-
__Description:__ The version of the serializer software.
131+
__Format:__ [purl specification](https://github.com/package-url/purl-spec)
132+
__Required:__ No
133+
__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
152134

153135
#### meta.source.uri
154136
__Type:__ String
@@ -183,6 +165,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
183165
## Version History
184166
| Version | Introduced in | Changes |
185167
| --------- | ------------------------------------------------------ | --------------------------------------- |
168+
| 2.0.0 | Current version | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
186169
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |
187170
| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. |
188171

‎eiffel-vocabulary/EiffelActivityTriggeredEvent.md‎

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -134,28 +134,10 @@ __Required:__ No
134134
__Description:__ The name of the event sender.
135135

136136
#### meta.source.serializer
137-
__Type:__ Object
138-
__Format:__
139-
__Required:__ No
140-
__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
141-
142-
##### meta.source.serializer.groupId
143-
__Type:__ String
144-
__Format:__ groupId
145-
__Required:__ Yes
146-
__Description:__ The groupId of the serializer software.
147-
148-
##### meta.source.serializer.artifactId
149137
__Type:__ String
150-
__Format:__ artifactId
151-
__Required:__ Yes
152-
__Description:__ The artifactId of the serializer software.
153-
154-
##### meta.source.serializer.version
155-
__Type:__ String
156-
__Format:__ version
157-
__Required:__ Yes
158-
__Description:__ The version of the serializer software.
138+
__Format:__ [purl specification](https://github.com/package-url/purl-spec)
139+
__Required:__ No
140+
__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
159141

160142
#### meta.source.uri
161143
__Type:__ String
@@ -190,6 +172,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
190172
## Version History
191173
| Version | Introduced in | Changes |
192174
| --------- | ------------------------------------------------------ | --------------------------------------- |
175+
| 2.0.0 | Current version | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
193176
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |
194177
| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. |
195178

‎eiffel-vocabulary/EiffelAnnouncementPublishedEvent.md‎

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -122,28 +122,10 @@ __Required:__ No
122122
__Description:__ The name of the event sender.
123123

124124
#### meta.source.serializer
125-
__Type:__ Object
126-
__Format:__
127-
__Required:__ No
128-
__Description:__ The [GAV](https://maven.apache.org/guides/mini/guide-naming-conventions.html) coordinates of the serializer software used to construct the event.
129-
130-
##### meta.source.serializer.groupId
131-
__Type:__ String
132-
__Format:__ groupId
133-
__Required:__ Yes
134-
__Description:__ The groupId of the serializer software.
135-
136-
##### meta.source.serializer.artifactId
137125
__Type:__ String
138-
__Format:__ artifactId
139-
__Required:__ Yes
140-
__Description:__ The artifactId of the serializer software.
141-
142-
##### meta.source.serializer.version
143-
__Type:__ String
144-
__Format:__ version
145-
__Required:__ Yes
146-
__Description:__ The version of the serializer software.
126+
__Format:__ [purl specification](https://github.com/package-url/purl-spec)
127+
__Required:__ No
128+
__Description:__ The identity of the serializer software used to construct the event, in [purl format](https://github.com/package-url/purl-spec).
147129

148130
#### meta.source.uri
149131
__Type:__ String
@@ -178,6 +160,7 @@ __Description:__ The encrypted digest. The cryptographic hash function and the d
178160
## Version History
179161
| Version | Introduced in | Changes |
180162
| --------- | ------------------------------------------------------ | --------------------------------------- |
163+
| 2.0.0 | Current version | Introduced purl identifiers instead of GAVs (see [Issue 182](https://github.com/eiffel-community/eiffel/issues/182)) |
181164
| 1.1.0 | [edition-toulouse](../../../tree/edition-toulouse) | Multiple links of type FLOW_CONTEXT allowed. |
182165
| 1.0.0 | [edition-bordeaux](../../../tree/edition-bordeaux) | Initial version. |
183166

0 commit comments

Comments
 (0)