Runtime View

RAML2AGL Generation

Fig. 9 presents the sequence of the raml2agl run for automatically generate APP Class, WebSocketApi, AGL Service and Service Class.

@startuml participant raml2agl participant "RAML Model" as model participant "Jinja 2 Templates Engine" as jinja participant "Filesystem" as fs activate raml2agl raml2agl --> model : Read RAML model raml2agl --> raml2agl: RAML to JSON model raml2agl --> jinja : Load templates ... alt "--service" == Generate AGL Service == raml2agl -> jinja : Get AGL Service template jinja --> raml2agl raml2agl -> jinja : Render AGL Service template jinja --> raml2agl raml2agl --> fs : Write generated AGL Service (*.cpp) == Generate Service Class == raml2agl -> jinja : Get Service Class template jinja --> raml2agl raml2agl -> jinja : Render Service Class template jinja --> raml2agl raml2agl --> fs : Write generated Service Class (*.cpp and *.h) else "--app" == Generate APP Class == raml2agl -> jinja : Get APP Class template jinja --> raml2agl raml2agl -> jinja : Render APP Class template jinja --> raml2agl raml2agl --> fs : Write generated APP Class (*.cpp and *.h) raml2agl --> fs : Copy WebSocketApi.cpp and WebSocketApi.h end alt "-v" raml2agl --> raml2agl : Print JSON Model end deactivate raml2agl @enduml

Fig. 9 RAML2AGL Generation

AGL Service Start

It’s important to have some insight on how AGL Services are initialized and how the Unix Web Socket gets created. Therefore, Fig. 10 shows this process.

@startuml actor Systemd participant "AGL App Framework" as af participant "AGL Service" as service participant "Unix Web Socket" as ws ... On System Start Up ... Systemd --> af : Start activate af af -> af : Start services activate af af --> ws : <<create>> With service's API Name activate ws af --> service : Start service activate service service --> ws : Listen ... @enduml

Fig. 10 AGL Service Start

Web Socket Communication

The Web Socket Communication can only happen after the AGL Service is already running, thus the Unix Web Socket was already created and the RESTfull API is being served. Fig. 11 shows the sequence how the entire communication takes place.

@startuml actor User as user participant APP as app participant "APP Class" as app_class participant "Unix Web Socket" as ws participant "AGL Service" as service participant "Service Class" as service_class activate service activate ws user --> app : Start APP activate app app --> app_class : <<create>> activate app_class app_class -> ws : Connect \\nto 'api_name' \\nWeb Socket ws -> app_class activate app_class ... app -> app_class : 'APP Class'.method(params) app_class -> app_class : Marshal params \\nas JSON app_class --> ws : Request \\nverb=method \\nwith JSON app_class -> app_class : Start wait loop activate app_class ws --> service : Request \\nverb=method \\nwith JSON service -> service : Call verb's callback activate service service --> service : Unmarshal \\nJSON \\ninto params service -> service_class : 'Service Class'.method(params) activate service_class service_class -> service deactivate service_class service --> service : Marshal \\nresulting \\nparams as JSON service --> ws : Reply with JSON deactivate service ws --> app_class : Reply with JSON deactivate app_class ws --> app_class : Unmarshal \\nJSON \\ninto vars app_class --> app_class : Update params \\nwith vars app_class --> app ... user --> app : Stop APP app --> app_class : <<destroy>> app_class -> ws : Disconnect ws -> app_class deactivate app_class deactivate app_class deactivate app @enduml

Fig. 11 Web Socket Communication

Note that the Application using the APP Class will have the entire Web Socket communication abstracted as simple method calls. Hence, an RPC model is implemented on top of the RESTful API. Fig. 12 shows this abstracted communication sequence.

@startuml actor User as user participant APP as app participant "APP Class" as app_class user --> app : Start APP activate app app --> app_class : <<create>> activate app_class ... app -> app_class : 'APP Class'.method(params) app_class --> app ... user --> app : Stop APP app --> app_class : <<destroy>> deactivate app_class deactivate app @enduml

Fig. 12 Web Socket Communication