Skip to content

Commit f89ef15

Browse files
xlakannUmadevi-Kapu
xlakann
authored and
Umadevi-Kapu
committed
Read the documentation for REMReM semantics in Opensource (#122)
1 parent b1115d3 commit f89ef15

8 files changed

+184
-2
lines changed

‎README.md

+9-2
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,7 @@
2323
[![Coverage Status](https://coveralls.io/repos/github/eiffel-community/eiffel-remrem-semantics/badge.svg?branch=master)](https://coveralls.io/github/eiffel-community/eiffel-remrem-semantics?branch=master)
2424
[![](https://jitpack.io/v/eiffel-community/eiffel-remrem-semantics.svg)](https://jitpack.io/#eiffel-community/eiffel-remrem-semantics)
2525

26-
Eiffel semantics is designed to implement new Eiffel messaging standard. Further documentation is provided at the following link: [https://eiffel-community.github.io/eiffel-remrem-semantics/](https://eiffel-community.github.io/eiffel-remrem-semantics/).
27-
26+
Eiffel semantics is designed to implement the Eiffel messaging standard.
2827
# About this repository
2928
The contents of this repository are licensed under the [Apache License 2.0](./LICENSE).
3029

@@ -34,3 +33,11 @@ To get involved, please see [Code of Conduct](./CODE_OF_CONDUCT.md) and [contrib
3433
This repository forms part of the Eiffel Community. Eiffel is a protocol for technology agnostic machine-to-machine communication in continuous integration and delivery pipelines, aimed at securing scalability, flexibility and traceability. Eiffel is based on the concept of decentralized real time messaging, both to drive the continuous integration and delivery system and to document it.
3534

3635
Visit [Eiffel Community](https://eiffel-community.github.io) to get started and get involved.
36+
37+
## Documentation
38+
39+
1. [**Introduction**](wiki/index.md)
40+
2. [**Installation**](wiki/installation.md)
41+
3. [**Compatibility**](wiki/compatibility.md)
42+
4. [**Usage**](wiki/usage.md)
43+
5. [**Templates**](wiki/templates.md)

‎wiki/compatibility.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## Compatibility
2+
3+
* Maven 3.6.1 and greater versions
4+
* JDK 1.8 and greater versions
5+
6+
For supporting latest features, Eiffel REMReM Semantics should use the latest version of [Eiffel REMReM Protocol Interface](https://github.com/eiffel-community/eiffel-remrem-protocol-interface).
7+
8+
Eiffel REMReM Semantics maintained by [EiffelCommunity](https://github.com/eiffel-community)

‎wiki/howToUseSemantics.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
## How to use semantics
2+
3+
To import the project, add below mentioned dependencies in pom.xml.
4+
5+
<repositories>
6+
<repository>
7+
<id>jitpack.io</id>
8+
<url>https://jitpack.io</url>
9+
</repository>
10+
</repositories>
11+
<dependency>
12+
<groupId>com.github.eiffel-community</groupId>
13+
<artifactId>eiffel-remrem-semantics</artifactId>
14+
<version>x.x.x</version>
15+
</dependency>
16+
17+
Or add below mentioned dependencies to gradle build script.
18+
19+
repositories {
20+
...
21+
maven { url 'https://jitpack.io' }
22+
}
23+
dependencies {
24+
compile("com.github.eiffel-community:eiffel-remrem-semantics:x.x.x")
25+
}
26+
27+
Eiffel REMReM Semantics contains implementation of Eiffel REMReM Protocol Interface. All methods of interface MsgService are implemented by SemanticsService class: generateMsg, getEventId, getEventType, getSupportedEventTypes, getEventTemplate, getServiceName, validateMsg, generateRoutingKey. Also in this class could be implemented more methods depending on the needs of developer.
28+
29+
The main task of Eiffel Semantics is to check a correctness of Eiffel message. Project contains JSON schemas for each Eiffel event type. If you need to create new event type, you need to define the JSON schema for this event.
30+
31+
Each of Eiffel data types, for example links, gav, etc have its implementation in schema. If you need to extend event with some custom field, the JSON schema for this field and serializer should be created for it. Also event JSON schema need to be updated.
32+
33+
During the verification process input JSON for SemanticsService is updated with the protocol related fields, for example id.
34+
35+
All Eiffel events consist of 3 logical JSON objects: meta, data and links. The meta object contains meta-information describing the event: when it was created, where it came from, its type etc. The data object contains all fields specific to the event type – the payload of the event – including trace links to non-Eiffel entities. It is described in detail per event type. The links object is an array of trace links to other Eiffel events.
36+
Please refer [Eiffel Remrem Protocol Interface](https://github.com/eiffel-community/eiffel-remrem-protocol-interface) to get more information on event types.
37+
38+
## Messages Table
39+
40+
Refer [Event-Templates](templates.md) of current official Eiffel events along with their templates.
41+
42+
Eiffel REMReM Semantics maintained by [EiffelCommunity](https://github.com/eiffel-community)

‎wiki/index.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
## Introduction
2+
3+
Eiffel REMReM Semantics is a set of protocol defined messages that contains templates and schemas for Eiffel message types. It implements the Eiffel REMReM Protocol Interface. Eiffel REMReM Semantics is used to check, generate and validate Eiffel messages. This project contains JSON schemas to validate JSON message to met the Eiffel protocol. Semantics generate Eiffel events from both [Eiffel Protocol](https://github.com/eiffel-community/eiffel-remrem-protocol-interface) and [Operations Extension](https://github.com/Ericsson/eiffel-operations-extension).
4+
This project contains information about how to form a routing key that will be added to the generated message.
5+
6+
Refer [Installation](installation.md) and [Usage](usage.md) links for more information on REMReM-Semantics.
7+
8+
Eiffel REMReM Semantics maintained by [EiffelCommunity](https://github.com/eiffel-community)

‎wiki/installation.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
## Installation
2+
3+
This project does not need any installation. It is used as external library that will be included as a dependency to other projects.
4+
5+
This project is build by maven, by executing following commands:
6+
7+
`mvn clean install`
8+
9+
The produced jar file will be stored in /eiffel-remrem-semantics/target/
10+
11+
To update the schemas in semantics with latest changes in Eiffel Operation repo schemas execute the maven profile **process-schemas** like below
12+
13+
`mvn clean install -P process-schemas`
14+
15+
By executing the process-schemas profile you will get the latest schemas from both eiffel repository and eiffel-operations repository.
16+
17+
After updating the schemas execute the profile **generate-events** to generate pojo clases by using updated schemas.
18+
19+
`mvn clean install -P generate-events`
20+
21+
### Note:
22+
23+
Execute the above mentioned maven profiles in order what they were declared if there is any change in schemas of eiffel or eiffel-operations repository.
24+
25+
Eiffel REMReM Semantics maintained by [EiffelCommunity](https://github.com/eiffel-community)

‎wiki/routingAndBindingKeyConcepts.md

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
## Routing and Binding key concepts
2+
3+
Eiffel protocol uses RabbitMQ as a message broker. It accepts and forwards messages. You can think about it as a post office: when you put the mail that you want posting in a post box, you can be sure that Mr. Postman will eventually deliver the mail to your recipient. In this analogy, RabbitMQ is a post box, a post office and a postman.
4+
5+
Each message in RabbitMQ must be posted to one or more exchanges. A binding is a relationship between an exchange and a queue. This can be simply read as: the queue is interested in messages from this exchange. The routing algorithm behind an exchange is simple - a message goes to the queues whose binding key exactly matches the routing key of the message.
6+
7+
An exchange is responsible for the routing of the messages to the different queues. An exchange accepts messages from the producer application and routes them to message queues with help of header attributes, bindings and routing keys.
8+
9+
A binding is a "link" that you set up to bind a queue to an exchange.
10+
11+
The routing key is a message attribute. The exchange might look at this key when deciding how to route the message to queues (depending on exchange type).
12+
13+
Topic exchanges route messages to queues based on wildcard matches between the routing key and something called the routing pattern specified by the queue binding. Messages are routed to one or many queues based on a matching between a message routing key and this pattern.
14+
15+
The routing key must be a list of words, delimited by a period (.), examples are "eiffel.activity.#" and "eiffel.activity.started.#". All of these routing keys will match the event that comes with a tag "eiffel.activity.started.notag" which in this case identifies event that is produced by eiffel protocol, the event family is activity, the event type is started. The routing patterns may contain an asterisk ("*") to match a word in a specific position of the routing key (e.g. a routing pattern of "eiffel.*.*.notag.#" will only match routing keys where the first word is "eiffel" and the fourth word is "notag"). A pound symbol ("#") indicates match on zero or more words (e.g. a routing pattern of "eiffel.artifact.#" matches any routing keys beginning with "eiffel.artifact").
16+
17+
The consumers indicate which topics they are interested in (like subscribing to a feed for an individual tag). The consumer creates a queue and sets up a binding with a given routing pattern to the exchange. All messages with a routing key that match the routing pattern will be routed to the queue and stay there until the consumer consumes the message.
18+
19+
## Eiffel routing convention
20+
21+
The routing key is concatenated from five entities: the event protocol, family, the event type, any custom tag and domain
22+
The routing key format for Eiffel REMReM Semantics:
23+
24+
`eiffel.<family>.<type>.<tag>.<domain>`
25+
26+
* <family> is a family name for a group of events, e.g. "activity".
27+
* <type> represents the event, e.g. "triggered".
28+
* <tag> is a field which carries no meaning for Eiffel itself, but may be used by users to implement a custom categorization scheme on which message routing may be applied. The tag must NOT contain any dots, as this will deny the receiver the ability to anticipate the word sequence of the binding key and must not exceed 16 characters in length. It is reserved for future use. Defaults to "notag".
29+
* <domain> The domain from which the message is sent. The value of the domain will fetch from Eiffel event if empty the value is fetch from the remrem publish configuration. domain can be suffixed by a user domain part that the user can specify with -ud option. For more information on domain, see [this link](https://github.com/eiffel-community/eiffel/blob/master/eiffel-syntax-and-usage/the-meta-object.md#metasourcedomainid).
30+
31+
The routing key for EiffelArtifactCreatedEvent would be eiffel.artifact.created.notag.eiffeltestdomain.sweden.rem002
32+
33+
##Limitation
34+
35+
The maximum limit for RabbitMQ routing key is 255 characters and as an Eiffel product we reserve some characters to form the binding /routing keys.
36+
37+
Eiffel REMReM Semantics maintained by [EiffelCommunity](https://github.com/eiffel-community)

‎wiki/templates.md

+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
### Templates
2+
This page shows the event types and their templates.Templates for Eiffel events to be used with [REMReM Generate](https://github.com/eiffel-community/eiffel-remrem-generate) are found below.
3+
4+
Template can be downloaded and all fields labeled as required are mandatory to fill.
5+
Templates are available from eiffel-remrem-semantics-0.2.5 version.
6+
7+
Templates are in full JSON syntax and filenames are in lowercase from eiffel-remrem-semantics-0.3.5 version.
8+
9+
You can download the templates and use them in REMReM generate.
10+
11+
| S.No | Family | Type | Name | Abbrevation | Comments |
12+
|:----------:|:-------------:|:------:|:-----:|:----:|:-----:|
13+
| 1 | activity | canceled | [EiffelActivityCanceledEvent](../src/main/resources/templates/eiffelactivitycanceledevent.json) | ActC | Available from 0.2.2 |
14+
| 2 | activity | finished | [EiffelActivityFinishedEvent](../src/main/resources/templates/eiffelactivityfinishedevent.json) | ActF | Available from 0.1.9 |
15+
| 3 | activity | started | [EiffelActivityStartedEvent](../src/main/resources/templates/eiffelactivitystartedevent.json) | ActS | Available from 0.2.2 |
16+
| 4 | activity | triggered | [EiffelActivityTriggeredEvent](../src/main/resources/templates/eiffelactivitytriggeredevent.json) | ActT | Available from 0.2.2 |
17+
| 5 | announcement | info | [EiffelAnnouncementPublishedEvent](../src/main/resources/templates/eiffelannouncementpublishedevent.json) | AnnP | Available from 0.2.2 |
18+
| 6 | artifact | created | [EiffelArtifactCreatedEvent](../src/main/resources/templates/eiffelartifactcreatedevent.json) | ArtC | Available from 0.2.2 |
19+
| 7 | artifact | published | [EiffelArtifactPublishedEvent](../src/main/resources/templates/eiffelartifactpublishedevent.json) | ArtP | Available from 0.2.2 |
20+
| 8 | artifact | reused | [EiffelArtifactReusedEvent](../src/main/resources/templates/eiffelartifactreusedevent.json) | ArtR | Available from 0.2.2 |
21+
| 9 | cm | composition | [EiffelCompositionDefinedEvent](../src/main/resources/templates/eiffelcompositiondefinedevent.json) | CD | Available from 0.2.2 |
22+
| 10 | artifact | modified | [EiffelConfidenceLevelModifiedEvent](../src/main/resources/templates/eiffelconfidencelevelmodifiedevent.json) | CLM | Available from 0.2.2 |
23+
| 11 | cm | environment | [EiffelEnvironmentDefinedEvent](../src/main/resources/templates/eiffelenvironmentdefinedevent.json) | ED | Available from 0.2.2 |
24+
| 12 | flowcontext | defined | [EiffelFlowContextDefinedEvent](../src/main/resources/templates/eiffelflowcontextdefinedevent.json) | FCD | Available from 0.2.2 |
25+
| 13 | test | issueverified | [EiffelIssueVerifiedEvent](../src/main/resources/templates/eiffelissueverifiedevent.json) | IV | Available from 0.2.2 |
26+
| 14 | cm | scmchange | [EiffelSourceChangeCreatedEvent](../src/main/resources/templates/eiffelsourcechangecreatedevent.json) | SCC | Available from 0.2.2 |
27+
| 15 | cm | scmproposedchange | [EiffelSourceChangeSubmittedEvent](../src/main/resources/templates/eiffelsourcechangesubmittedevent.json) | SCS | Available from 0.2.2 |
28+
| 16 | test | canceled | [EiffelTestCaseCanceledEvent](../src/main/resources/templates/eiffeltestcasecanceledevent.json) | TCC | Available from 0.2.5 |
29+
| 17 | test | casefinished | [EiffelTestCaseFinishedEvent](../src/main/resources/templates/eiffeltestcasefinishedevent.json) | TCF | Available from 0.2.2 |
30+
| 18 | test | casestarted | [EiffelTestCaseStartedEvent](../src/main/resources/templates/eiffeltestcasestartedevent.json) | TSS | Available from 0.2.2 |
31+
| 19 | test | triggered | [EiffelTestCaseTriggeredEvent](../src/main/resources/templates/eiffeltestcasetriggeredevent.json) | TCT | Available from 0.2.5 |
32+
| 20 | test | execution | [EiffelTestExecutionRecipeCollectionCreatedEvent](../src/main/resources/templates/eiffeltestexecutionrecipecollectioncreatedevent.json) | TERCC | Available from 0.2.2 |
33+
| 21 | test | suitefinished | [EiffelTestSuiteFinishedEvent](../src/main/resources/templates/eiffeltestsuitefinishedevent.json) | TSF | Available from 0.2.2 |
34+
| 22 | test | suitestarted | [EiffelTestSuiteStartedEvent](../src/main/resources/templates/eiffeltestsuitestartedevent.json) | TSS | Available from 0.2.2 |
35+
| 23 | artifact | deployed | [EiffelArtifactDeployedEvent](../src/main/resources/templates/eiffelartifactdeployedevent.json) | ArtD | Available from 0.3.2 |
36+
| 24 | service | allocated | [EiffelServiceAllocatedEvent](../src/main/resources/templates/eiffelserviceallocatedevent.json) | ServA | Available from 0.3.2 |
37+
| 25 | service | deployed | [EiffelServiceDeployedEvent](../src/main/resources/templates/eiffelservicedeployedevent.json) | ServDe | Available from 0.3.2 |
38+
| 26 | service | discontinued | [EiffelServiceDiscontinuedEvent](../src/main/resources/templates/eiffelservicediscontinuedevent.json) | ServDi | Available from 0.3.2 |
39+
| 27 | service | returned | [EiffelServiceReturnedEvent](../src/main/resources/templates/eiffelservicereturnedevent.json) | ServR | Available from 0.3.2 |
40+
| 28 | service | started | [EiffelServiceStartedEvent](../src/main/resources/templates/eiffelservicestartedevent.json) | ServSta | Available from 0.3.2 |
41+
| 29 | service | stopped | [EiffelServiceStoppedEvent](../src/main/resources/templates/eiffelservicestoppedevent.json) | ServSto | Available from 0.3.2 |
42+
| 30 | alert | raised | [EiffelAlertRaisedEvent](../src/main/resources/templates/eiffelalertraisedevent.json) | AlerR | Available from 0.3.9 |
43+
| 31 | alert | acknowledged | [EiffelAlertAcknowledgedEvent](../src/main/resources/templates/eiffelalertacknowledgedevent.json) | AlerA | Available from 0.3.9 |
44+
| 32 | alert | ceased | [EiffelAlertCeasedEvent](../src/main/resources/templates/eiffelalertceasedevent.json) | AlerC | Available from 0.3.9 |
45+
| 33 | test | issuedefined | [EiffelIssueDefinedEvent](../src/main/resources/templates/eiffelissuedefinedevent.json) | IssD | Available from 2.0.0 |

‎wiki/usage.md

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
## Usage
2+
3+
[Example on how to use the semantics protocol library](howToUseSemantics.md)
4+
5+
[Routing and Binding Key concepts](routingAndBindingKeyConcepts.md)
6+
7+
Please refer to [Eiffel Syntax](https://github.com/eiffel-community/eiffel/tree/master/eiffel-syntax-and-usage) and [Eiffel Vocabulary](https://github.com/eiffel-community/eiffel/tree/master/eiffel-vocabulary) for usage.
8+
Please note that **meta.id**, **meta.time**, **meta.version** are generated by Eiffel REMReM Generate.
9+
10+
Eiffel REMReM Semantics maintained by [EiffelCommunity](https://github.com/eiffel-community)

0 commit comments

Comments
 (0)