extending.md

Extending RagConnect

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

{% raw %}

• Add a new handler ABCHandler.jadd, similar to the existing handlers.
• In handler.mustache, add further methods if needed for handler usage in the application code (similar to {{rootNodeName}}.{{SetupWaitUntilReadyMethodName}} for mqtt)
• In receiveDefinition.mustache and sendDefinition.mustache: add a new case in the switch statements defining the logic to happen upon connect and disconnect for both definitions. If the new protocol is close to a PUSH semantic, follow mqtt. If it is closer to PULL semantic, follow rest. {% endraw %}

Within ragconnect.base/src/main/jastadd

In Handlers.jrag: Add a new attribute RagConnect.abcHandler() returning the resolved handler

Within ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler

In Compiler.java:

• Add a new choice for --protocols similar to the existing ones
• Add a newly constructed handler in setConfiguration with the needed fields (definition file name within resources directory, commonly ABCHandler.jadd; class name of the handler; unique name for the protocol; whether the handler is used, i.e., if it was given in --protocols)

Furthermore, new test cases are appreciated, see below.

Writing Tests

To add new tests, have a look at the module ragconnect.tests. It has three parts:

1. In src/test/01-input/* are the specifications that are going to be compiled (in principle using the steps described in the guide to add RagConnect).
2. In src/test/java, the jUnit 5 test classes are implemented. They mostly correspond 1-to-1 to a directory of the first part.
3. In build.gradle the instructions how to compile the specifications using the gradle plugin PreprocessorPlugin (org.jastadd.preprocessor:testing).

Specifications

Every specification must have at least a README.md to describe the purpose of the test, a grammar Test.relast, and a RagConnect specification Test.connect. Usually an aspect file Test.jadd is included.

Test Classes

Based on jUnit 5, the test classes testing some behaviour. If sending and/or receiving functionality is used, consider extending AbstractMqttTest in order to avoid duplicate code. In case of extending this class, please order the methods according to their lifecycle, i.e.:

• createModel
• setupReceiverAndConnect
• communicateSendInitialValue
• communicateOnlyUpdatedValue
• closeConnections

Within AbstractMqttTest, an MqttHandler named publisher is available to publish content. Some convenience methods are provided in TestUtils, e.g., the DefaultMappings, and mqttUri to prepend "mqtt://" and the correct host for the mqtt broker (localhost or a CI-specific host). All tests are required to run both locally, and within the CI.

build.gradle

Using the PreprocessorPlugin, the build process can be written concisely in three parts per task:

task compileTreeAllowedTokens(type: RagConnectTest) {
    ragconnect {
        outputDir = file('src/test/02-after-ragconnect/treeAllowedTokens')
        inputFiles = [file('src/test/01-input/treeAllowedTokens/Test.relast'),
                      file('src/test/01-input/treeAllowedTokens/Test.connect'),
                      file('src/test/01-input/treeAllowedTokens/TestDependencies.connect')]
        rootNode = 'Root'
    }
    relast {
        useJastAddNames = true
        grammarName = 'src/test/03-after-relast/treeAllowedTokens/treeAllowedTokens'
        serializer = 'jackson'
    }
    jastadd {
        jastAddList = 'JastAddList'
        packageName = 'treeAllowedTokens.ast'
        inputFiles = [file('src/test/01-input/treeAllowedTokens/Test.jadd')]
    }
}