Commit fd0dd20b authored by René Schöne's avatar René Schöne
Browse files

Update pages.

parent 83a338a9
# Adding `ragconnect` to your project
# Adding `RagConnect` to your project
If you want to use `ragconnect`, the currently suggested way is to first build the jar from this repository:
If you want to use `RagConnect`, the currently suggested way is to first build the jar from the [RagConnect repository](https://git-st.inf.tu-dresden.de/jastadd/ragconnect):
```bash
git clone https://git-st.inf.tu-dresden.de/jastadd/ragconnect.git
cd ragconnect
./gradlew jar
ls ragconnect.base/build/libs/
......@@ -15,7 +16,7 @@ cp ragconnect.base/build/libs/ragconnect-<version>.jar ../your-project/libs/ragc
cd ../your-project/
```
Finally, this jar has to be integrated into your build process. In case, [Gradle](https://gradle.org/) is used, a task could look like the following (example taken from the [ros2rag usecase](https://git-st.inf.tu-dresden.de/jastadd/ros2rag)). The path to the jar files may need to be changed according to your project structure.
Finally, this jar has to be integrated into your build process. In case, [Gradle](https://gradle.org/) is used, a task could look like the following (example taken from the [ros2rag usecase](https://git-st.inf.tu-dresden.de/jastadd/ros2rag)). The path to the jar file may need to be changed according to your project structure.
```groovy
task ragConnect(type: JavaExec) {
......@@ -33,7 +34,7 @@ task ragConnect(type: JavaExec) {
}
```
This is typically accompanied with a task to invoke the [RelAst compiler](http://relational-rags.eu/) and the [JastAdd gradle plugin](https://plugins.gradle.org/plugin/org.jastadd). The additional arguments "--useJastAddNames", "--listClass", "--jastAddList" and "--resolverHelper" to relast are not required. Please see the user manual of the RelAst compiler for more information.
This is typically accompanied with a task to invoke the [RelAst compiler](http://relational-rags.eu/) and the [JastAdd gradle plugin](https://plugins.gradle.org/plugin/org.jastadd). The additional arguments `--useJastAddNames`, `--listClass`, `--jastAddList` and `--resolverHelper` to relast are not required. Please see the user manual of the RelAst compiler for more information.
```groovy
task relastToJastAdd(type: JavaExec) {
......@@ -65,11 +66,10 @@ relastToJastAdd.dependsOn ragConnect
## Introduced dependencies
Ragconnect itself does not introduce dependencies.
RagConnect itself does not introduce dependencies.
However, depending on the selected protocols (see [compiler options](/using#compiler-options)), additional dependencies are required.
| Protocol | Dependency (Gradle format) | Remarks |
|-|-|-|
| `mqtt` | `group: 'org.fusesource.mqtt-client', name: 'mqtt-client', version: '1.15'` | Mqtt is selected by default, so this dependency therefore is required "by default". Might work with other versions as well. |
| `rest` | `group: 'com.sparkjava', name: 'spark-core', version: '2.9.2'` | Might work with other versions as well. For debugging, it is beneficial to include an implementation for [SLF4J](http://www.slf4j.org/). |
# Extending `ragconnect`
# Extending `RagConnect`
To add a new communication protocol `ABC`, the following locations have to be changed:
To add a new communication protocol, the following locations have to be changed (replace `ABC` and `abc` with the name of the protocol):
- within `ragconnect.base/src/main/resources`
- add a new handler `ABCHandler`, if appropriate, similar to the existing handlers
- add a new template `abc.mustache` containing an aspect `ABC` initializing the handler (if any) similar to the existing protocols
- in `ragconnect.mustache`: add `{{#usesABC}}{{> abc}}{{/usesABC}}` and `{{#usesABC}}{{abcHandlerField}}.close();{{/usesABC}}`, respectively if appropriate
- in `receiveDefinition.mustache` and `sendDefinition.mustache`: add a new case in the switch statement defining the logic to happen for both definitions. If the new protocol is close to a PUSH semantic, follow `mqtt`. If it is closer to PULL semantic, follow `rest`.
- within `ragconnect.base/src/main/jastadd`
- in `backend/Configuration`: add a new static boolean flag `usesABC` to indicate whether the protocol is used
- in `backend/Generation`:
- add new attributes for type `MRagConnect` for handler-attribute and handler-field, if needed
- add attributes for newly introduced references in changed mustache templates, if any
- in `backend/MustacheNodesToYAML`:
- add key-value-pair for `usesABC` (and handler, if any)
- add key-value-pairs for newly introduced referemces in changed mustache templates, if any
- in `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler/Compiler.java`
- add a new choice for `--protocols` similar to the existing ones
- set the flag `usesABC` if the choice is given.
- add code to add the handler to the list `handlers` if the choice is given, i.e., if `ASTNode.usesABC`
Within `ragconnect.base/src/main/resources`:
- Add a new handler `ABCHandler`, if appropriate, similar to the existing handlers
- Add a new template `abc.mustache` containing an aspect `ABC` initializing the handler (if any) similar to the existing protocols
- In `ragconnect.mustache`: add `{{#usesABC}}{{> abc}}{{/usesABC}}` and `{{#usesABC}}{{abcHandlerField}}.close();{{/usesABC}}`, respectively if appropriate
- In `receiveDefinition.mustache` and `sendDefinition.mustache`: add a new case in the switch statement defining the logic to happen for both definitions. If the new protocol is close to a PUSH semantic, follow `mqtt`. If it is closer to PULL semantic, follow `rest`.
Within `ragconnect.base/src/main/jastadd`:
- In `backend/Configuration`: add a new static boolean flag `usesABC` to indicate whether the protocol is used
- In `backend/Generation`:
- Add new attributes for type `MRagConnect` for handler-attribute and handler-field, if needed
- Add attributes for newly introduced references in changed mustache templates, if any
- In `backend/MustacheNodesToYAML`:
- Add key-value-pair for `usesABC` (and handler, if any)
- Add key-value-pairs for newly introduced referemces in changed mustache templates, if any
In `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler/Compiler.java`:
- Add a new choice for `--protocols` similar to the existing ones
- Set the flag `usesABC` if the choice is given.
- Add code to add the handler to the list `handlers` if the choice is given, i.e., if `ASTNode.usesABC`
Furthermore, new test cases are appreciated. They can be added in the [ragconnect.rests repository](https://git-st.inf.tu-dresden.de/jastadd/ragconnect-tests)
......@@ -6,7 +6,7 @@
RagConnect Documentation
========================
RagConnect is a preprocessor to enable easy connection to/from models based on `Reference Attribute Grammars <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.8792&rep=rep1&type=pdf>`_ and `Relation Reference Attribute Grammars <https://doi.org/10.1016/j.cola.2019.100940>`_ built with `JastAdd <http://jastadd.org/>`_.
`RagConnect <https://git-st.inf.tu-dresden.de/jastadd/ragconnect>`_ is a preprocessor to enable easy connection to/from models based on `Reference Attribute Grammars <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.8792&rep=rep1&type=pdf>`_ and `Relation Reference Attribute Grammars <https://doi.org/10.1016/j.cola.2019.100940>`_ built with `JastAdd <http://jastadd.org/>`_.
.. toctree::
:maxdepth: 2
......
# Inner workings of `ragconnect`
# Inner workings of `RagConnect`
![ros2rag-process](images/ros2rag-process.png)
- `ragconnect` uses the [relast-preprocessor](https://git-st.inf.tu-dresden.de/jastadd/relast-preprocessor) to parse `.relast` grammar files. This results in an ASTNode of type `Program`.
- it further uses a dedicated parser for `.connect` files containing endpoint-, mapping-, and dependency-definitions. This results in an ASTNode of type `RagConnect`.
- the goal is to generate an aspect file containing setters and getters of tokens referred to by endpoint-definitions
- we use [mustache](https://mustache.github.io/) (currently its [Java version](https://github.com/spullara/mustache.java)) making use of partials resulting in a set of `.mustache` files located in `ragconnect.base/src/main/resources`
- the generation process uses an intermediate NTA of type `MRagConnect` defined in `MustacheNodes.relast` to separate this generation concern from the content of the DSL
- there are aspect files for `Navigation` (mainly isX/asX attributes), `Analysis` (lookup attributes), `Printing`, `backend/Mappings` (default mappings)
- one of the main aspects is `backend/Generation` containing attributes to construct the `MRagConnect` NTA and all necessary attributes used within the mustache templates
- the other main aspect (which is currently not really used) is `backend/MustacheNodesToYAML.jrag` containing the transformation from a `MRagConnect` subtree to a `Document` subtree defined by `YAML.relast`. This is used to generate a YAML file containing the data used by mustache. It can be used by the default mustache implementation together with the templates.
`RagConnect` uses the [relast-preprocessor](https://git-st.inf.tu-dresden.de/jastadd/relast-preprocessor) to parse `.relast` grammar files. This results in an ASTNode of type `Program`.
It further uses a dedicated parser for `.connect` files containing endpoint-, mapping-, and dependency-definitions. This results in an ASTNode of type `RagConnect`.
The goal is to generate an aspect file containing setters and getters of tokens referred to by endpoint-definitions
We use [mustache](https://mustache.github.io/) (currently its [Java version](https://github.com/spullara/mustache.java)) making use of partials resulting in a set of `.mustache` files located in `ragconnect.base/src/main/resources`.
The generation process uses an intermediate NTA of type `MRagConnect` defined in `MustacheNodes.relast` to separate this generation concern from the content of the DSL
There are aspect files for `Navigation` (mainly isX/asX attributes), `Analysis` (lookup attributes), `Printing`, `backend/Mappings` (default mappings)
One of the main aspects is `backend/Generation` containing attributes to construct the `MRagConnect` NTA and all necessary attributes used within the mustache templates
The other main aspect (which is currently not really used) is `backend/MustacheNodesToYAML.jrag` containing the transformation from a `MRagConnect` subtree to a `Document` subtree defined by `YAML.relast`. This is used to generate a YAML file containing the data used by mustache. It can be used by the default mustache implementation together with the templates.
# Use cases with `ragconnect`
# Use cases with `RagConnect`
## 1⃣ MPM4CPS Paper - Codename 'Ros2Rag'
In the publication [*"Connecting conceptual models using Relational Reference Attribute Grammars"*](https://doi.org/10.1145/3417990.3421437) ( DOI still pending), a use case involving a simulated robot arm and two different models conencted to it was shown.
In the publication [*"Connecting conceptual models using Relational Reference Attribute Grammars"*](https://doi.org/10.1145/3417990.3421437), a use case involving a simulated robot arm and two different models conencted to it was shown.
One model was used to ensure a low speed of the robot when within a safety zone (purple boxes in the picture below), and the other model executes a workflow to control the robot.
![Screenshot of Gazebo](images/robo3d.png)
......
# Using `ragconnect` -- an example
# Using `RagConnect` -- an example
## Preparation
......@@ -119,14 +119,14 @@ Additional options are as follows.
| `--version` | No (false) | Print version info and exit (reused JastAdd option) |
| `--o` | No (`.`) | Output directory (reused JastAdd option) |
All files to be process have to be passed as arguments. Their type is decided by the file extension (`ast` and `relast` for input grammars, `connect` and `ragconnect` for ragconnect definitions file).
All files to be process have to be passed as arguments. Their type is decided by the file extension (`ast` and `relast` for input grammars, `connect` and `ragconnect` for RagConnect definitions file).
## Remarks
When constructing the AST and connecting it, one should always set dependencies before connecting, especially if updates already arriving for receiving endpoints.
Otherwise, updates might not be propagated after setting dependencies, if values are equal after applying transformations of mapping definitions.
As an example, when using the following grammar and ragconnect-definitions ...
As an example, when using the following grammar and definitions for RagConnect ...
```bnf
A ::= <Input:int> /<Output:String>/ ;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment