Workflows, Worker and Visitors

This page is under construction. Of course, you may read it, but the page is far from complete and far from being error-free.

Please send any suggestions for changes to reinhard.budde AT iais.fraunhofer.de

Front-end requests trigger REST methods in the server. If programs and/or configuration (XML) are part of the request, these are transformed to an abstract syntax tree (AST, object tree of Phrase-s) and processed in a pipeline (workflow) of workers. The workers of an robot plugin can be found in the plugin properties, e.g. in ev3lejosv1.properties:

robot.plugin.worker.validate.robot = de.fhg.iais.roberta.worker.validate.Ev3BrickValidatorWorker
robot.plugin.worker.validate.sim = de.fhg.iais.roberta.worker.validate.Ev3SimValidatorWorker
robot.plugin.worker.collect.hardware = de.fhg.iais.roberta.worker.collect.Ev3UsedHardwareCollectorWorker
robot.plugin.worker.collect.method = de.fhg.iais.roberta.worker.collect.Ev3UsedMethodCollectorWorker
robot.plugin.worker.generate = de.fhg.iais.roberta.worker.codegen.Ev3JavaGeneratorWorker
robot.plugin.worker.setup = de.fhg.iais.roberta.worker.CompilerSetupWorker
robot.plugin.worker.compile = de.fhg.iais.roberta.worker.compile.Ev3LejosCompilerWorker
robot.plugin.worker.transfer = de.fhg.iais.roberta.worker.TransferWorker
robot.plugin.worker.generatesimulation=de.fhg.iais.roberta.worker.codegen.Ev3StackMachineGeneratorWorker
robot.plugin.worker.transform.two2three=de.fhg.iais.roberta.worker.Two2ThreeTransformerWorker
robot.plugin.worker.transform.three2threeone=de.fhg.iais.roberta.worker.Three2ThreeOneTransformerWorker

The workflows is defined in the same resource,too:

robot.plugin.workflow.showsource = validate.robot,collect.hardware,collect.method,generate
robot.plugin.workflow.compile = validate.robot,collect.hardware,collect.method,generate,setup,compile
robot.plugin.workflow.run = validate.robot,collect.hardware,collect.method,generate,setup,compile,transfer
robot.plugin.workflow.getsimulationcode = validate.sim,collect.hardware,generatesimulation
robot.plugin.workflow.runnative = setup,compile,transfer
robot.plugin.workflow.compilenative=setup,compile
robot.plugin.workflow.transform=transform.two2three,transform.three2threeone

For example, the REST-service class ProjectWorkflowRestController handles a REST-request @Path("/source") which shows the target program generated from the program XML by executing the method

Project project = request2project(wfRequest, httpSessionState, this.robotCommunicator, true, false);
ProjectService.executeWorkflow("showsource", project);

executeWorkflow retrieves the workflow definition and executes one worker after the other. If a worker fails, the AST component that effects the failure must be annotated with a warning or error. The workflow is cancelled, the program XML is generated from the AST and sent back to the client. All worker implement the IWorker interface and follow usually the GOF template method pattern (see example below). The template method is execute. In most cases worker delegate their work to visitors. Visitors in turn follow the well known GOF visitor pattern and visit the AST(s).

As example take the Ev3BrickValidatorWorker. All concrete validators subclass the abstract class AbstractValidatorWorker. The class implements the template method execute and adds the hook method getVisitor to get the concrete visitor. Subclasses of AbstractValidatorWorker have to implement the hook method getVisitor only. Thus Ev3BrickValidatorWorker subclasses AbstractValidatorWorker and returns an object of Ev3BrickValidatorVisitor. The template method in turn calls phrase.accept(visitor); for the top phases and the visitor collects data and validates the program and the configuration.

The challenge when writing visitors is to not loose overview. Note, that all robot plugins share common language constructs as number constants, if, while, variables. Visiting these parts should be done once and not repeated for every robot plugin. Sometimes there are subtle differences (some string operations missing, some data types missing). But in any case robots add their actors and sensors to the AST and these must be visited together with the common parts. This is reflected in the inheritance hierarchy:

Ev3BrickValidatorVisitor
  extends AbstractBrickValidatorVisitor
    extends AbstractProgramValidatorVisitor
      extends AbstractCollectorVisitor

list of existing (or desired) workers:

• consistency of the configuration (needs configuration)

  • ardu pin check, ev3 slots unique
  • configuration block names unique
  • callibot 1x ... extend for all systems

• consistency of the program (needs program and configuration)

  • this is a proposal, currently a small amount of consistency checks exist, and separate hardware and method collector are used
  • empty block checker
  • checked sensor/actor blocks versus configuration
  • assembles used hardware and used (externally defined) methods (design decision: new visitor?)
  • typechecks the AST (design decision: new visitor?)
  • called NEPO procedures exists and the signatures match
  • defined and used variables match

• simulation consistency validator

  • checks whether used blocks are legal

• generate source (i.e. the target language as Java, C++, Python)

• generate simulation (generates stack machine code)

• compiler setup worker

• compile

• transfer (to the target system)

• transformer (backward compatibility with NEPO versions before version 3.1)

• resetFirmware (reset firmware to the factory default)

• save (for the nao; others too, when no compiler is called?)

  • creates a temporary directory and stores the saved program into that directory
  • prepares the transfer to the nao
  • have other other plugins similiar functionality? Refactor

design decision: one consistency checker (program and configuration) or two: one for the program and one for both

further work:

• complete this text
• select one visitor (program validator visitor for calliope or ev3?) and refactor it.