User Tools

Site Tools


v070:layout

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
v070:layout [2018/10/05 14:23]
djnemeth [Specifying expected communication between lifelines]
v070:layout [2018/10/08 09:08] (current)
djnemeth [Execution]
Line 1: Line 1:
-====== Diagram Language ​Guide for version 0.7.0 ======+====== Diagram Language ​Description ​for version 0.7.0 ======
  
-In txtUML, class and state machine diagrams can be defined to visualize model structure and behavior. ​To express ​test cases for expected communication, sequence diagrams ​can be used.+In txtUML, class and state machine diagrams can be defined to visualize model structure and behavior. ​Moreover, ​test cases for expected communication can also be specified in the form of sequence diagrams.
  
 ===== Class and State Machine Diagrams ===== ===== Class and State Machine Diagrams =====
Line 14: Line 14:
 This class must contain an inner class definition, inheriting from ''​Layout''​. The actual layout constraints can be written as annotations on this inner class. This class must contain an inner class definition, inheriting from ''​Layout''​. The actual layout constraints can be written as annotations on this inner class.
  
-<​code>​+<​code ​java>
 class MyDiagram extends ClassDiagram { class MyDiagram extends ClassDiagram {
   // layout constraints as annotations   // layout constraints as annotations
Line 38: Line 38:
 Example: Model contains these classes: **A**, **B** and **C**. Example: Model contains these classes: **A**, **B** and **C**.
 {{ :​v020:​examplesimplediagram.png?​200|}} {{ :​v020:​examplesimplediagram.png?​200|}}
-<​code>​+<​code ​java>
 class MyClassDiagram extends ClassDiagram { class MyClassDiagram extends ClassDiagram {
   @North(val = A.class, from = B.class)   @North(val = A.class, from = B.class)
Line 47: Line 47:
 </​code>​ </​code>​
 Example: The class **A** contains these states: **Init**, **Disabled** and **Active**. Example: The class **A** contains these states: **Init**, **Disabled** and **Active**.
-<​code>​+<​code ​java>
 class MyStateDiagram extends StateMachineDiagram<​A>​ { class MyStateDiagram extends StateMachineDiagram<​A>​ {
   @Left(val = Init.class, from = Disabled.class)   @Left(val = Init.class, from = Disabled.class)
Line 67: Line 67:
  
 Example: Model contains these classes: **C**, **E**, **D**, **O**, **R**, **S1** and **S2**. Example: Model contains these classes: **C**, **E**, **D**, **O**, **R**, **S1** and **S2**.
-<​code>​+<​code ​java>
 class MyDiagram extends ClassDiagram { class MyDiagram extends ClassDiagram {
   @Row({R.class,​ E.class, D.class})   @Row({R.class,​ E.class, D.class})
Line 86: Line 86:
 Example: Model contains these classes: **A** and **B**. Model contains these links: **L** (A - B) and **R** (A - A). Example: Model contains these classes: **A** and **B**. Model contains these links: **L** (A - B) and **R** (A - A).
 {{ :​v020:​examplelinkdiagram.png?​150|}} {{ :​v020:​examplelinkdiagram.png?​150|}}
-<​code>​+<​code ​java>
 class MyDiagram extends ClassDiagram { class MyDiagram extends ClassDiagram {
   @North(val = L.class, from = A.class)   @North(val = L.class, from = A.class)
Line 102: Line 102:
 A group can be specified by defining a class inheriting either from ''​NodeGroup''​ or from ''​LinkGroup''​. The elements of the group can be specified with the ''​@Contains''​ annotation. A group can contain model elements of the corresponding type or other groups containing elements of the corresponding type. A group can be specified by defining a class inheriting either from ''​NodeGroup''​ or from ''​LinkGroup''​. The elements of the group can be specified with the ''​@Contains''​ annotation. A group can contain model elements of the corresponding type or other groups containing elements of the corresponding type.
  
-<​code>​+<​code ​java>
   @Contains({A.class,​ B.class})   @Contains({A.class,​ B.class})
   class NG1 extends NodeGroup {}   class NG1 extends NodeGroup {}
 </​code>​ </​code>​
  
-<​code>​+<​code ​java>
   @Contains({L.class,​ J.class})   @Contains({L.class,​ J.class})
   class LG1 extends LinkGroup {}   class LG1 extends LinkGroup {}
Line 114: Line 114:
 If the given group is a ''​NodeGroup'',​ the annotation ''​@Alignment''​ can be used to set the alignment of its elements, using items of enum //​hu.elte.txtuml.layout.lang.AlignmentType//,​ i.e. ''​TopToBottom'',​ ''​BottomToTop'',​ ''​RightToLeft''​ or ''​LeftToRight''​. If the given group is a ''​NodeGroup'',​ the annotation ''​@Alignment''​ can be used to set the alignment of its elements, using items of enum //​hu.elte.txtuml.layout.lang.AlignmentType//,​ i.e. ''​TopToBottom'',​ ''​BottomToTop'',​ ''​RightToLeft''​ or ''​LeftToRight''​.
  
-<​code>​+<​code ​java>
   @Contains({NG1.class,​ C.class})   @Contains({NG1.class,​ C.class})
   @Alignment(AlignmentType.TopToBottom)   @Alignment(AlignmentType.TopToBottom)
Line 132: Line 132:
  
 Example: Model contains these classes: **A**, **B**, **C** and **D**. Example: Model contains these classes: **A**, **B**, **C** and **D**.
-<​code>​+<​code ​java>
 class MyDiagram extends ClassDiagram { class MyDiagram extends ClassDiagram {
   @Contains({C.class,​ D.class})   @Contains({C.class,​ D.class})
Line 147: Line 147:
  
 Example: Example:
-<​code>​+<​code ​java>
   class MyPhantom extends Phantom {}   class MyPhantom extends Phantom {}
   //...   //...
Line 164: Line 164:
  
 Example: Model contains these classes: **A** and **B**. Example: Model contains these classes: **A** and **B**.
-<​code>​+<​code ​java>
 class MyDiagram extends ClassDiagram { class MyDiagram extends ClassDiagram {
   @Show(A.class)   @Show(A.class)
Line 178: Line 178:
  
 Example: Model contains these classes: **A** and **B**. Example: Model contains these classes: **A** and **B**.
-<​code>​+<​code ​java>
 class MyDiagram extends ClassDiagram { class MyDiagram extends ClassDiagram {
   @Spacing(0.6)   @Spacing(0.6)
Line 195: Line 195:
  
 ==== General structure ==== ==== General structure ====
-A sequence diagram description is a Java class inheriting from class ''​SequenceDiagram''​+A sequence diagram description is a Java class inheriting from class [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v070/​api/​java/​hu/​elte/​txtuml/​api/​model/​seqdiag/​SequenceDiagram.html|SequenceDiagram]]
  
 Lifelines can be defined as class members in a diagram description. To give an ordering between them on the generated diagram, the ''​Position''​ annotation can be used.  Lifelines can be defined as class members in a diagram description. To give an ordering between them on the generated diagram, the ''​Position''​ annotation can be used. 
 The parameter is a positive priority value, and lifelines will appear in ascending order according to the given position. The parameter is a positive priority value, and lifelines will appear in ascending order according to the given position.
  
-Sequence diagrams inherit two public methods: ''​initialize''​ and ''​run''​. By overriding the former, model initialization can be expressed ​(typically ''​Action.create''​ and ''​Action.link''​ calls are placed here). Expected communication between lifelines can be defined in method ''​run''​. ​+Sequence diagrams inherit two public methods: ''​initialize''​ and ''​run''​. By overriding the former, model initialization can be specified ​(typically ''​Action.create''​ and ''​Action.link''​ calls are placed here). Expected communication between lifelines can be defined in method ''​run''​. ​
 Please note that only action code is allowed in ''​initialize''​ and only sequence diagram code (static methods of class ''​Sequence''​) is allowed in ''​run'',​ otherwise an exception is thrown during the execution. Please note that only action code is allowed in ''​initialize''​ and only sequence diagram code (static methods of class ''​Sequence''​) is allowed in ''​run'',​ otherwise an exception is thrown during the execution.
  
Line 208: Line 208:
  
   * ''​Sequence.send(from,​ msg, to)'':​ **from** is expected to send a message to **to** which is equal to **msg**.   * ''​Sequence.send(from,​ msg, to)'':​ **from** is expected to send a message to **to** which is equal to **msg**.
-  * ''​Sequence.fromActor(msg,​ to)'':​ **msg** should be sent to **to** by an actor.+  * ''​Sequence.fromActor(msg,​ to)'':​ **msg** should be sent to **to** by an actor. Reaching this call, the sequence diagram executor actually sends the message to the target.
   * ''​Sequence.assertState(obj,​ s)'':​ immediately after the target of the most recent ''​Sequence.send''​ or ''​Sequence.fromActor''​ call has received the message, **obj** is in state **s** (also see [[v070:​layout#​Condition evaluation during execution]]).   * ''​Sequence.assertState(obj,​ s)'':​ immediately after the target of the most recent ''​Sequence.send''​ or ''​Sequence.fromActor''​ call has received the message, **obj** is in state **s** (also see [[v070:​layout#​Condition evaluation during execution]]).
  
Line 215: Line 215:
 <code java> <code java>
 class MySeqDiagram extends SequenceDiagram { class MySeqDiagram extends SequenceDiagram {
- 
   @Position(1)   @Position(1)
   A a; // A is a ModelClass   A a; // A is a ModelClass
Line 231: Line 230:
     Sequence.send(a,​ new MySignal(), b); // MySignal is a signal     Sequence.send(a,​ new MySignal(), b); // MySignal is a signal
   }   }
- 
 } }
 </​code>​ </​code>​
Line 237: Line 235:
 ==== Fragments ==== ==== Fragments ====
 Similarly to the UML standard, there are also some advanced constructions called fragments, which can be expressed with Java keywords. ​ Similarly to the UML standard, there are also some advanced constructions called fragments, which can be expressed with Java keywords. ​
-  * Alternative and optional fragments can be written as if-then(-else) statements. +  * Alternative and optional fragments can be written as //if-then(-else)// statements. 
-  * Loop fragments are denoted by for, while and do-while loops. ​+  * Loop fragments are denoted by //for////while// and //do-while// loops. ​
   * Parallel behavior can be expressed via parallel fragments, e.g. when the exact order of messaging is unknown or not relevant between sets of signal sendings. These sets can be defined as lambda expressions. See the {{v070:​demo.zip|demo models}} for concrete examples.   * Parallel behavior can be expressed via parallel fragments, e.g. when the exact order of messaging is unknown or not relevant between sets of signal sendings. These sets can be defined as lambda expressions. See the {{v070:​demo.zip|demo models}} for concrete examples.
  
 ==== Execution ==== ==== Execution ====
-The execution of the diagram can be configured by setting the execution mode. For this purpose, the ''​ExecutionMode''​ annotation ​of the ''​run''​ method ​can be used.+The execution of the diagram can be configured by setting the execution mode. For this purpose, the ''​ExecutionMode''​ annotation ​can be used on the ''​run''​ method .
  
-Regardless of the chosen mode, the entire messaging defined in ''​run''​ should ​happen ​in the model during the execution. ''​ExecMode.STRICT''​ does not allow any other communication,​ while ''​ExecMode.LENIENT''​ does.+Regardless of the chosen mode, the entire messaging defined in ''​run''​ should ​occur in the model during the execution. ''​ExecMode.STRICT''​ does not allow any other communication,​ while ''​ExecMode.LENIENT''​ does.
  
 === Condition evaluation during execution === === Condition evaluation during execution ===
  
-During testing, the model and sequence diagram ​runs parallelly, and the executor ​keeps checking ​whether the communication in the model conforms to the expected behavior.  +During testing, the model and the sequence diagram ​run in parallel, and the executor ​constantly checks ​whether the communication in the model conforms to the expected behavior.  
-Thus a model-dependent condition in the sequence diagram code (e.g. in an OPT, ALTLOOP fragment) is evaluated in the actual state of the model.  +model-dependent condition in the sequence diagram code (e.g. in an //OPT////ALT// or //LOOP// fragment) is evaluated in the actual state of the model.  
-In sequence diagram code, in general, ​after a given ''​Sequence.send(from, msg, to)'',​ the model stays in the state where it is at the moment when **to** has just received and processed ​the message sent by **from**. +In sequence diagram code, in general, ​between two communication assertions (i.e. ''​Sequence.send'' ​and ''​Sequence.fromActor''​ calls), the model stays in the state where it was at the moment when the signal specified in the previous assertion was received and processed by the target of that assertion.
 ==== Limitations ==== ==== Limitations ====
-Unfortunately,​ the actual sequence diagram communication API cannot be used to express expected communication when a reference of sender or target is not visible from sequence diagram code (e.g. objects created inside a model class). Thus some models are currently not testable. 
  
 +Currently, the sequence diagram communication API cannot be used to express expected communication when a reference of a sender or target is not visible from sequence diagram code, that is, in the case you simply don't have the object references to pass to ''​Sequence''​ methods.
v070/layout.1538742201.txt.gz · Last modified: 2018/10/05 14:23 by djnemeth