Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Henshin/Units"

m (Unit creation in graphical editor: Visually separate screenshots)
m (Independent Unit: Clarify caption)
(35 intermediate revisions by the same user not shown)
Line 1: Line 1:
In Henshin, control flow is specified using '''units'''. Units have a fixed number of sub-units, allowing for arbitrary nesting. This article describes the available units.
+
[[Category:Henshin]][[Category:Modeling]]
 +
 
 +
In Henshin, control flow is specified using '''units'''.
 +
Units have a fixed number of sub-units, allowing for arbitrary nesting.
 +
This article describes the available units.
 +
 
 +
Units can be categorized by their possible number of sub-units.
 +
For '''unary units''' the number of sub-units is exactly one.
 +
'''Multi-units''' have an arbitrary number of sub-units.
 +
The specific unit ''Conditional Unit'' has two or three sub-units.
 +
 
 +
Each unit checks the executability of at least one sub-unit, if a sub-unit exists.
 +
This check means the sub-unit is executed.
  
 
== Usage ==
 
== Usage ==
  
 
=== Unit creation in graphical editor ===
 
=== Unit creation in graphical editor ===
 +
 +
[[Image:Henshin_Units_Creation_GraphicalEditor.png|250px|thumb|right|Create unit]]
  
 
To add a unit to a Henshin project in the [[Henshin/Graphical Editor|graphical editor]], first open the ''*.henshin_diagram'' file.
 
To add a unit to a Henshin project in the [[Henshin/Graphical Editor|graphical editor]], first open the ''*.henshin_diagram'' file.
 
Then select ''Unit'' from the ''Palette'' on the right of the window.
 
Then select ''Unit'' from the ''Palette'' on the right of the window.
 
Afterwards left-click any empty space of the Henshin diagram and choose the desired unit from the appearing menu.
 
Afterwards left-click any empty space of the Henshin diagram and choose the desired unit from the appearing menu.
 +
 +
[[Image:Henshin_Units_Add_Invocation.png|250px|thumb|right|Add sub-unit]]
  
 
If the selected unit is a Multi-Unit, some sub-units have to be added manually.
 
If the selected unit is a Multi-Unit, some sub-units have to be added manually.
 
Therefore select ''Invocation'' from the ''Palette'' and click on the according Multi-Unit.
 
Therefore select ''Invocation'' from the ''Palette'' and click on the according Multi-Unit.
 
Then type the name of the desired rule or unit.
 
Then type the name of the desired rule or unit.
 
+
Currently every sub-unit is inserted behind all existing sub-units, which is especially relevant for ''PriorityUnit''s and ''SequentialUnit''s.
[[Image:Henshin_Units_Creation_GraphicalEditor.png|250px]] → [[Image:Henshin_Units_Add_Invocation.png|250px]]
+
If that's not the desired behaviour it is recommended to use the ''Properties'' view or the tree-based editor for sub-unit insertion or reordering.
  
 
=== Unit creation in tree-based editor ===
 
=== Unit creation in tree-based editor ===
Line 24: Line 40:
 
[[Image:Henshin_Units_Creation_TreeEditor.png|350px]]
 
[[Image:Henshin_Units_Creation_TreeEditor.png|350px]]
  
== Multi-Units ==
+
== Unary Units ==
  
=== Sequential Unit===
+
A Unary Unit has exactly one sub-unit.
  
[[Image:Henshin_Sequential_Unit.png|right]]
+
=== Loop Unit ===
  
; Number of sub-units
+
[[Image:Henshin_Loop_Unit.png|right|thumb|Apply A as often as possible]]
: arbitrary (0..*)
+
; Available Flags/Properties
+
: of type boolean
+
:* strict
+
:* rollback
+
; Execution successful
+
: if
+
:; strict=true
+
:: all sub-units successful
+
:; strict=false
+
:: at least one sub-unit successful or no sub-units
+
; Execution unsuccessful
+
: if
+
:; strict=true
+
:: one sub-unit unsuccessful
+
:; strict=false
+
:: none of a non-zero number of sub-units successful
+
; Control flow
+
: The sub-units are executed in the given order.
+
:; strict=false, rollback=true/false
+
:: If one of the sub-units cannot be executed, the next sub-unit is executed.
+
:; strict=true, rollback=false
+
:: If one of the sub-units cannot be executed, the execution stops.
+
:; strict=true, rollback=true
+
:: If one of the sub-units cannot be executed, the execution stops and previous executions are reverted.
+
  
=== Priority Unit ===
+
* '''Number of sub-units:''' 1
 +
* '''Available Flags/Properties:''' ''none''
 +
* '''Execution successful:''' always
 +
* '''Control flow:''' The sub-unit is executed as often as it is executable.
 +
* '''Examples:''' [https://www.eclipse.org/henshin/examples.php?example=java2statemachine Java2StateMachine],  [https://www.eclipse.org/henshin/examples.php?example=ecore2genmodel Ecore2Genmodel]
  
[[Image:Henshin_Priority_Unit.png|right]]
+
=== Iterated Unit ===
  
; Number of sub-units
+
[[Image:Henshin_Iterated_Unit.png|right|thumb|Apply A three times]]
: arbitrary (0..*)
+
; Available Flags/Properties
+
: ''none''
+
; Execution successful
+
: tbd
+
; Execution unsuccessful
+
: tbd
+
; Control flow
+
: The sub-units are checked in the given order for executability. The first sub-unit found to be executable is executed.
+
  
=== Independent Unit ===
+
* '''Number of sub-units:''' 1
 +
* '''Available Flags/Properties:''' iterations (integer), strict, rollback (both of type boolean)
 +
* '''Execution successful if:'''
 +
** '''strict=true:''' all iterations successful
 +
** '''strict=false:''' at least one iteration successful
 +
* '''Control flow:''' The sub-unit is executed as often as specified in the ''iterations'' property.
 +
** '''strict=false, rollback=true/false:''' If one of the iterations cannot be executed, the next iteration is executed. As the execution never stops, the ''rollback'' flag has no effect.
 +
** '''strict=true, rollback=false:''' If one of the iterations cannot be executed, the execution stops.
 +
** '''strict=true, rollback=true:''' If one of the iterations cannot be executed, the execution stops and previous executions are reverted.
 +
* '''Examples:''' [https://www.eclipse.org/henshin/examples.php?example=combpattern Grid & Comb Pattern]
  
[[Image:Henshin_Independent_Unit.png|right]]
+
== Conditional Unit ==
  
; Number of sub-units
+
[[Image:Henshin_Conditional_Unit.png|right|thumb|If A applicable then apply B, else apply C]]
: arbitrary (0..*)
+
; Available Flags/Properties
+
: ''none''
+
; Execution successful
+
: tbd
+
; Execution unsuccessful
+
: tbd
+
; Control flow
+
: The sub-units are checked in nondeterministic order for executability. The first sub-unit found to be executable is executed.
+
  
== Unary Units ==
+
* '''Number of sub-units:''' 2 or 3
 +
* '''Available Flags/Properties:''' ''none''
 +
* '''Execution successful if:''' ''if'' unit and ''then'' unit are successful or ''if'' unit is unsuccessful while ''else'' unit is successful or not present.
 +
* '''Control flow:''' If a match for the ''if'' unit can be found, the ''then'' unit is executed. Otherwise, if present, the ''else'' unit is executed.
 +
* '''Examples:''' [https://www.eclipse.org/henshin/examples.php?example=java2statemachine Java2StateMachine]
  
=== Loop Unit ===
+
== Multi-Units ==
  
[[Image:Henshin_Loop_Unit.png|right]]
+
A Multi-Unit has an arbitrary number of sub-units.
  
; Number of sub-units
+
=== Sequential Unit===
: 1
+
; Available Flags/Properties
+
: ''none''
+
; Execution successful
+
: tbd
+
; Execution unsuccessful
+
: tbd
+
; Control flow
+
: The sub-unit is executed as often as it is executable.
+
  
=== Iterated Unit ===
+
[[Image:Henshin_Sequential_Unit.png|right|thumb|Apply A then B then C]]
  
[[Image:Henshin_Iterated_Unit.png|right]]
+
* '''Number of sub-units:''' arbitrary (0..*)
 +
* '''Available Flags/Properties:''' strict, rollback (both of type boolean)
 +
* '''Execution successful if:'''
 +
** '''strict=true:''' all sub-units successful or no sub-units existing
 +
** '''strict=false:''' at least one sub-unit successful or no sub-units existing
 +
* '''Control flow: ''' The sub-units are executed in the given order.
 +
** '''strict=false:''' If one of the sub-units cannot be executed, the next sub-unit is executed. As the execution never stops, the ''rollback'' flag has no effect.
 +
** '''strict=true, rollback=false:''' If one of the sub-units cannot be executed, the execution stops.
 +
** '''strict=true, rollback=true:''' If one of the sub-units cannot be executed, the execution stops and previous executions are reverted.
 +
* '''Examples:''' [https://www.eclipse.org/henshin/examples.php?example=ecore2rdb Ecore2RDB], [https://www.eclipse.org/henshin/examples.php?example=java2statemachine Java2StateMachine],  [https://www.eclipse.org/henshin/examples.php?example=ecore2genmodel Ecore2Genmodel], [https://www.eclipse.org/henshin/examples.php?example=combpattern Grid & Comb Pattern], [https://www.eclipse.org/henshin/examples.php?example=giraph-movies Movies]
  
; Number of sub-units
+
=== Priority Unit ===
: 1
+
; Available Flags/Properties
+
: of type positive integer
+
:* iterations
+
: of type boolean
+
:* strict
+
:* rollback
+
; Execution successful
+
: if
+
:; strict=true
+
:: all iterations successful
+
:; strict=false
+
:: at least one iteration successful
+
; Execution unsuccessful
+
: if
+
:; strict=true
+
:: one iteration unsuccessful
+
:; strict=false
+
:: no iteration successful
+
; Control flow
+
: The sub-unit is executed as often as specified in the ''iterations'' property.
+
:; strict=false, rollback=true/false
+
:: If one of the iterations cannot be executed, the next iteration is executed.
+
:; strict=true, rollback=false
+
:: If one of the iterations cannot be executed, the execution stops.
+
:; strict=true, rollback=true
+
:: If one of the iterations cannot be executed, the execution stops and previous executions are reverted.
+
  
=== Conditional Unit ===
+
[[Image:Henshin_Priority_Unit.png|right|thumb|Try to apply A. If A not applicable, try B etc.]]
 +
 
 +
* '''Number of sub-units:''' arbitrary (0..*)
 +
* '''Available Flags/Properties:''' ''none''
 +
* '''Execution successful if:''' one sub-unit successful (Empty priority units always fail.)
 +
* '''Control flow:''' The sub-units are checked in the given order for executability. The first sub-unit found to be executable is executed.
 +
* '''Examples:''' [https://www.eclipse.org/henshin/examples.php?example=java2statemachine Java2StateMachine]
 +
 
 +
=== Independent Unit ===
  
[[Image:Henshin_Conditional_Unit.png|right]]
+
[[Image:Henshin_Independent_Unit.png|right|thumb|Choose A, B or C in non-deterministic order. If not applicable, try another one in non-deterministic order. If it is not applicable...]]
  
; Number of sub-units
+
* '''Number of sub-units:''' arbitrary (0..*)
: 2 or 3
+
* '''Available Flags/Properties:''' ''none''
; Available Flags/Properties
+
* '''Execution successful:''' one sub-unit succesful (Empty independent units always fail.)
: ''none''
+
* '''Control flow:''' The sub-units are checked in nondeterministic order for executability. The first sub-unit found to be executable is executed.
; Execution successful
+
* '''Examples:''' [https://www.eclipse.org/henshin/examples.php?example=ecore2genmodel Ecore2Genmodel]
: tbd
+
; Execution unsuccessful
+
: tbd
+
; Control flow
+
: tbd
+

Revision as of 09:28, 7 May 2018


In Henshin, control flow is specified using units. Units have a fixed number of sub-units, allowing for arbitrary nesting. This article describes the available units.

Units can be categorized by their possible number of sub-units. For unary units the number of sub-units is exactly one. Multi-units have an arbitrary number of sub-units. The specific unit Conditional Unit has two or three sub-units.

Each unit checks the executability of at least one sub-unit, if a sub-unit exists. This check means the sub-unit is executed.

Usage

Unit creation in graphical editor

Create unit

To add a unit to a Henshin project in the graphical editor, first open the *.henshin_diagram file. Then select Unit from the Palette on the right of the window. Afterwards left-click any empty space of the Henshin diagram and choose the desired unit from the appearing menu.

Add sub-unit

If the selected unit is a Multi-Unit, some sub-units have to be added manually. Therefore select Invocation from the Palette and click on the according Multi-Unit. Then type the name of the desired rule or unit. Currently every sub-unit is inserted behind all existing sub-units, which is especially relevant for PriorityUnits and SequentialUnits. If that's not the desired behaviour it is recommended to use the Properties view or the tree-based editor for sub-unit insertion or reordering.

Unit creation in tree-based editor

To add a unit to a Henshin project in the tree-based editor, first open the *.henshin file. Then right-click on the parent Module. Select New Child and afterwards the desired unit from the context menu. After creation the units can be edited in their Properties view.

Henshin Units Creation TreeEditor.png

Unary Units

A Unary Unit has exactly one sub-unit.

Loop Unit

Apply A as often as possible
  • Number of sub-units: 1
  • Available Flags/Properties: none
  • Execution successful: always
  • Control flow: The sub-unit is executed as often as it is executable.
  • Examples: Java2StateMachine, Ecore2Genmodel

Iterated Unit

Apply A three times
  • Number of sub-units: 1
  • Available Flags/Properties: iterations (integer), strict, rollback (both of type boolean)
  • Execution successful if:
    • strict=true: all iterations successful
    • strict=false: at least one iteration successful
  • Control flow: The sub-unit is executed as often as specified in the iterations property.
    • strict=false, rollback=true/false: If one of the iterations cannot be executed, the next iteration is executed. As the execution never stops, the rollback flag has no effect.
    • strict=true, rollback=false: If one of the iterations cannot be executed, the execution stops.
    • strict=true, rollback=true: If one of the iterations cannot be executed, the execution stops and previous executions are reverted.
  • Examples: Grid & Comb Pattern

Conditional Unit

If A applicable then apply B, else apply C
  • Number of sub-units: 2 or 3
  • Available Flags/Properties: none
  • Execution successful if: if unit and then unit are successful or if unit is unsuccessful while else unit is successful or not present.
  • Control flow: If a match for the if unit can be found, the then unit is executed. Otherwise, if present, the else unit is executed.
  • Examples: Java2StateMachine

Multi-Units

A Multi-Unit has an arbitrary number of sub-units.

Sequential Unit

Apply A then B then C
  • Number of sub-units: arbitrary (0..*)
  • Available Flags/Properties: strict, rollback (both of type boolean)
  • Execution successful if:
    • strict=true: all sub-units successful or no sub-units existing
    • strict=false: at least one sub-unit successful or no sub-units existing
  • Control flow: The sub-units are executed in the given order.
    • strict=false: If one of the sub-units cannot be executed, the next sub-unit is executed. As the execution never stops, the rollback flag has no effect.
    • strict=true, rollback=false: If one of the sub-units cannot be executed, the execution stops.
    • strict=true, rollback=true: If one of the sub-units cannot be executed, the execution stops and previous executions are reverted.
  • Examples: Ecore2RDB, Java2StateMachine, Ecore2Genmodel, Grid & Comb Pattern, Movies

Priority Unit

Try to apply A. If A not applicable, try B etc.
  • Number of sub-units: arbitrary (0..*)
  • Available Flags/Properties: none
  • Execution successful if: one sub-unit successful (Empty priority units always fail.)
  • Control flow: The sub-units are checked in the given order for executability. The first sub-unit found to be executable is executed.
  • Examples: Java2StateMachine

Independent Unit

Choose A, B or C in non-deterministic order. If not applicable, try another one in non-deterministic order. If it is not applicable...
  • Number of sub-units: arbitrary (0..*)
  • Available Flags/Properties: none
  • Execution successful: one sub-unit succesful (Empty independent units always fail.)
  • Control flow: The sub-units are checked in nondeterministic order for executability. The first sub-unit found to be executable is executed.
  • Examples: Ecore2Genmodel

Copyright © Eclipse Foundation, Inc. All Rights Reserved.