Agama DS candidate notation

This is a draft

Overview

A candidate graphical notation for Agama Developer Studio is presented here. In short, it is a simplification of the flowcharting notation most programmers are familiar with and is focused on the inherent peculiarities of Agama flows.

You may like to check this page before proceeding.

DSL's most-commonly used features

So far almost all bodies of implemented flows use just the following:

• Call
• Trigger
• RRF
• Finish
• Log
• Assignments and variable manipulations
• Repeat/Quit (rarely)
• When (without otherwise)

These hold enough power to do interesting stuff

When/Otherwise are the equivalents of C's if...else in case you don't know Agama DSL. Repeat/Quit resembles for...break

Note only Repeat and When are structural

When (w/o Otherwise) is common

A pattern that appears frequently in Agama flows is where upon a given condition the flow is simply terminated.

C-like example:

...
if (my boolean condition) {
    do A
    return X
}
do B
...

which is a better version than:

...
if (my boolean condition) {
    do A
    return X
} else {
    do B
    ...
}

Otherwise usage is a bit uncommon. Flows tend to look a lot like:

...
if (condition_1) {
    ...
}
...
if (condition_2) {
    ...
    if (condition_2_1) {
        ...
    }
    ...
}
...

no elses...

Proposal: No Otherwise

What if we don't offer an "else" equivalent in our graphical editor?

It turns out this brings some benefits for diagramming as we'll see later

Not allowed	Allowed
TODO	TODO

In the table above, a rectangle denotes a process which can be a single step, or composite (containining diamonds and rectangles inside)

Unable to avoid the "else" in a flow? it can be workarounded. Say we have:

if (cond) {
    B
} else {
    A
}

this can be re-arranged to:

execA = true
if (cond) {
    B
    execA = false
}
if (execA) {
    A
}

a bit ugly, right

Proposed notation

Note this document does not cover how an Agama flow header should be specified. However, that's clearly an easy task.

1. Use a rectangle to represent one of:

   • Call
   • Trigger
   • RRF
   • Quit (see below)
   • Finish
   • A set of consecutive assignments and/or variable manipulations

2. Use an inverted dashed triangle to denote When (without otherwise). Think of it as the lower half of a diamond - I preferred it dashed because the (solid) inverted triangle is already used in flowcharting techniques for merging: when two or more sub-processes become one

3. No nesting: no rectangles/triangles inside rectangles/triangles

4. However, a set of consecutive rectangles can be grouped to configure iteration (Repeat). A Quit rectangle can appear at most once in a group of this kind

Layout rules

• Consecutive elements (rectangles and triangles) are layed out like a string of beads (i.e. in a thread/strand) horizontally from left to right
• No arrows to indicate direction, just an horizontal line
• Under a triangle a new horizontal line is originated and the rules apply again
• The last (right-most) element on a line originated by a triangle needs not to be chained to the next executable element in the upper line sequence. It is obvious the flow continues at the element to the right of the originating triangle. The flow may also terminate immediately if a Finish rectangle is reached
• The contents under a triangle can be collapsed to hide detail

Example

TODO

Text inside elements is descriptive. Actual details would be shown on hover, like the boolean expression applicable to the triangle.

More rules

• On a given line, there can be at most one Finish rectangle
• Call, Trigger, RRF, Quit, and Finish rectangles can hold any number of assignments/variable manipulations before the given operation is executed. This helps making diagrams more compact, specifically by grouping data manipulation statements directly related to the operation of interest
• Call, Trigger, RRF, and Quit can hold any number of Log statements anywhere

A more complete example

TODO

Benefits

• Simple representation:

  • No arrows needed
  • Hierarchical like a tree - in contrast to flow charts which resemble directed cyclic graphs
  • Collapsible

• Easy to follow: left to right, top-bottom-up

• Agama code generation should not be too hard this way

• With this notation, the UI editor is probably easier to code in comparison to using the classical programming flowchart notation

• ... and drag-and-drop may not be strictly necessary: one could right-click anywhere in an horizontal line to insert a component at that point

• Developers can benefit from this tool, specially when they are starting with Agama

Wish list

• When creating/editing a Trigger rectangle, allow to pick the flow to trigger from the list of existing registered flows

• When creating/editing a Call rectangle, allow to pick the Java class and method to invoke (like in "Actions" of former demo videos). This would be sophisticated