Update README with changes regarding v3 concepts (#229)

* Update README with  changes regarding  v3 concepts

* Update sipmc section

* Add changelog

* Update nav menu of mkdocks.yml

* Fix formatting in core.md

* Update docs

* Update middle component docs

---------

Co-authored-by: Leto Bukarica <[email protected]>

changelogs/documentation/update_readme_file.json

@@ -0,0 +1,5 @@
+{
+  "author": "Nemikor",
+  "pullrequestId": "229",
+  "message": "Update README.md with changes regarding v3 adapter structure and the concept of sipmc."
+}

docs/README.md

@@ -42,21 +42,22 @@ The integration logic is divided into different packages:
 
 The **Common** package provides the common data model inside domain for both systems and common util functionalities.
 
-**Domain**
+**Models**
 
-**Domain** package should contain only simple Java objects representing the respective domain
+**Models** package should contain only simple Java objects representing the respective domain
 in which the system connectors of an adapter operate, and should not contain any integration logic.
 All connectors should adapt the data models of their systems to or from this common model, 
 depending on data flow, due to their incompatibilities. 
 The domain can be seen as a kind of contract between the different system connectors,
 which ensures that they can communicate with each other. 
 It contains common data model which uniforms the data models from all integration sides.
 
-**Connectors**
+**Connector groups**
 
-Each **Connector** is designed to communicate with the associated external systems, thus all classes found in a connector
-should only relate to their integration side. To enable this, their local domain objects are aligned with the API of an
-external systems they communicate with. In order to send a message from one system connector
+Each **Connector group** is designed to contain connectors which communicate with the associated external systems, 
+thus all classes found in a connector group should only relate to their integration side. 
+To enable this, their local domain objects are aligned with the API of an
+external systems they communicate with. In order to send a message from one system 
 to another, the local domain objects must be mapped to the shared domain object. Furthermore, this means that a message
 from system A is mapped to the shared domain object and then from the shared domain object to the model of system B and
 vice versa, due to their bidirectional nature.
@@ -68,9 +69,9 @@ since integrated systems use the same communication data model sometimes.
 Each connector will have the following structure:
 
 - `config` - a place for any configuration classes
-- `sink` - here we should define Camel routes
+- `connectors` - here we should define inbound and outbound connectors
 - `transformers` - it should contain classes for adapting the connector model to common domain model.
-- `domain` - (optional) it may contain the data model of the system.
+- `models` - (optional) it may contain the data model of the system.
 - `processors` - camel processors
 - `validators` - camel validators
 
@@ -112,11 +113,11 @@ Before development, check the following [Installation guide](installation.md).
 Once you have your adapter you can do the following steps:
 
 - Run `mvn clean install`
-- Create common Data Model inside domain package
+- Create common Data Models inside models package
 - Add necessary dependencies
-- Add RouteBuilders inside "sink" package in connectors
-- Add classes which transform system data models to or from common domain model in "transformers" package in connectors (if needed)
-- Add any configuration classes for a specific system inside "config" package in connectors
+- Add Connectors inside "connectors" package in connector groups
+- Add classes which transform system data models to or from common domain model in "transformers" package in connector groups (if needed)
+- Add any configuration classes for a specific system inside "config" package in connector groups
 - Add general integration configuration in application.yml found inside resources
 - Run SIPApplication found inside base package
 - After the application is up and running you can check SIP's management API under [localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)
@@ -126,15 +127,6 @@ Once you have your adapter you can do the following steps:
 If you need to upgrade your adapter to a newer SIP Framework version, please follow this 
 [guide](./framework_version_upgrade.md).
 
-### How and why to use SIP Middle Component
-
-[SIP Middle Component](./middle-component.md) (sipmc) is a key concept of SIP Framework.
-As such it is used as a communication device between connectors.
-To make a clear distinction between connectors, the point of separation can be seen with sipmc.
-It marks the end or beginning of integration sides.
-Currently, sipmc works as either 1 to 1 connector or publish subscribe,
-based on the number of consumers, without any additional configuration.
-
 ### Adding additional Camel starters to the project
 
 The Maven dependency management techniques implemented in the SIP archetype give you the ability to easily add new
@@ -157,35 +149,38 @@ The same stands for adding Spring Boot starters - as they are managed in the par
 without explicitly stating version numbers. As a matter of fact, the overall dependency management performed by the
 Spring Boot is in place in integration adapters too.
 
-### Adding new System Connectors
+### Adding new Connector Groups
 
-By using the SIP archetype to create a new SIP adapter, by default there are two system connectors, designed to make it
+By using the SIP archetype to create a new SIP adapter, by default there are two connector groups, designed to make it
 more convenient to integrate systems. In case there are more than two systems, which need to be integrated, you need to add
-additional package to the project structure.
+additional connector groups to the project structure.
 
 The project structure usually looks like this:
 
 ```text
 fancy-sip-adapter
 ├───src/main/java/<package-path>
 │   ├───common
-│   │   ├───domain
+│   │   ├───config
 │   │   └───util
-│   ├───connectors
-│   │   ├───connector1
+│   ├───connectorgroups
+│   │   ├───connectorGroup1
 │   │   │   ├───config
 │   │   │   ├───transformer
 │   │   │   ├───processors
-│   │   │   ├───sink
+│   │   │   ├───connectors
 │   │   │   ├───validators
-│   │   │   └───domain
-│   │   └───connector2
+│   │   │   └───models
+│   │   └───connectorGroup2
 │   │       ├───config
 │   │       ├───transformer
 │   │       ├───processors
-│   │       ├───sink
+│   │       ├───connectors
 │   │       ├───validators
-│   │       └───domain
+│   │       └───models
+│   ├───scenarios
+│   │   ├───models
+│   │   └───definitions
 │   └───SIPApplication.java
 └───pom.xml
 ```
@@ -305,4 +300,11 @@ sip.security.ssl.client.key-store | Location of client keystore | String | /
 sip.security.ssl.client.key-store-password | Password of client keystore | String | /
 sip.security.ssl.client.key-store-type | Type of client keystore file | String | / |
 sip.security.ssl.client.key-alias | The alias (or name) under which the key is stored in the client keystore | String | / |
-sip.security.ssl.client.key-password | Password of the client key | String | / |
+sip.security.ssl.client.key-password | Password of the client key | String | / |
+
+
+### SIP Middle Component
+
+[SIP Middle Component](./middle-component.md) (sipmc) is a custom camel component used by the SIP Framework
+as a communication device between connectors.
+Currently, sipmc can be seen as part of integration scenarios as a tool for its lifecycle manipulation.

docs/core.md

@@ -138,7 +138,7 @@ All registered routes with basic info can be listed by using the following URI:
 GET /actuator/adapter-routes
 ```
 
-Getting only routes with sip middle component consumer:
+Getting only routes with sip middle component consumer (including all outbound connectors):
 
 ```
 GET /actuator/adapter-routes/sipmc
@@ -171,8 +171,9 @@ This can be achieved by using following URI:
 POST /actuator/adapter-routes/{routeId}/{operation}
 ```
 
-Executing desired operation on the routes without providing route id is possible on sip middle component. By specifying
-operation on the following URI, operation will be executed for all routes which has sip middle component as a consumer:
+It is also possible to execute desired operation on integration scenarios level via sip middle component. 
+By specifying the operation in the following URI, 
+it will be executed for all outgoing connectors inside the adapter, and any other consumer using sipmc:
 
 ```
 POST /actuator/adapter-routes/sipmc/{operation}
@@ -303,7 +304,7 @@ sip:
         showExchangeId: true
         showProperties: true
         maxChars: 100
- ```
+```
 
 Exchanges will contain the "traceSet" header, which appears as a list of ordered exchange Ids,
 appended based on EIP used in a route and separated by a coma. This allows to easily track the path of an message.

docs/middle-component.md

@@ -4,17 +4,14 @@
 
 ## Description
 
-SIP middle component relates to the key SIP concept - splitting integration logic into submodules (connectors).
-Combining connectors into one data flow is quite easy with Camel and can be done in many ways. However, if we
-do it with one of Camel's existing component, we couldn't be sure if it represents connection between connectors or just
-some intermediate routing within the single connector. If we (properly) use sipmc component,
-it provides a clear functional and visual distinction between a connector's ending or beginning.
-With it, adapter routes become more standardized and manageable.
-Middle component is also a point of higher control over Apache Camel flow, as it provides a placeholder for future customizations
-which will make it easier to bridge connectors in different ways, e.g. by using JMS broker implicitly if configured.
-
-Middle component hides connecting technology and makes connection of two sub-systems abstract and simple. Current version
-supports only in-memory connection channel implemented on top of Camel's SEDA component. It provides 1 to 1 and
+SIP middle component is a tool used by the SIP framework to link connectors inside adapters. 
+It's built as a custom Apache Camel component, used inside integration scenarios, 
+but it's also available to adapter developers. 
+The goal was to represent where one integration side ends and the other begins
+through clear functional and visual distinction (via graphical interface).
+
+Middle component hides connecting technology and makes connection of two sub-systems abstract and simple. 
+It supports only in-memory connection channel implemented on top of Camel's SEDA component. It provides 1 to 1 and
 publish-subscribe patterns and can support many channels in single adapter. Middle component can automatically determine
 the number of consumers for a specific channel and autoconfigure itself accordingly, as a 1 to 1 or publish-subscribe connector.
 In any case it will be autoconfigured with waitForTaskToComplete=always, meaning that it will wait for all asynchronous   
@@ -35,8 +32,7 @@ Multiple sipmc routes may exist with different channel names.
 
 When building adapter by using Declarative Structure sipmc is embedded and explicit usage is not necessary. 
 Sipmc is placed in Integration Scenario, and acts as a Camel route connection between Inbound and Outbound Connectors.
-
-Since the sipmc is already embedded, 
+This means all inbound connectors will end with sipmc, while outbound connectors will start with sipmc.
 
 ## Examples
 

mkdocs.yml

@@ -10,11 +10,12 @@ nav:
     - Installation Guide: installation.md
     - Archetype: archetype.md
     - Core: core.md
-    - Middle Component: middle-component.md
+    - Declarative Structure: declarative.md
     - Integration Starter: integration-starter.md
     - Starter Parent: starter-parent.md
     - Security: security.md
     - Test Kit: test-kit.md
+    - Middle Component: middle-component.md
     - Framework Version Upgrade: framework_version_upgrade.md
     - License: license.md
     - Contribution Guidelines: CONTRIBUTING.md