User Tools

Site Tools


v070:userguide

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
Last revision Both sides next revision
v070:userguide [2018/10/08 08:06]
djnemeth [Running and debugging models]
v070:userguide [2018/10/08 19:11]
djnemeth [Running and debugging models]
Line 47: Line 47:
   * ''​XtxtUML''​ for custom modelling syntax.   * ''​XtxtUML''​ for custom modelling syntax.
   * ''​JtxtUML''​ for Java syntax.   * ''​JtxtUML''​ for Java syntax.
-Both XtxtUML and JtxtUML models can be connected with Java code, can be run and debugged, and used as a source for Papyrus UML model generation.+Both XtxtUML and JtxtUML models can be connected with Java code, can be run and debugged, and used as a source for UML2 model generation.
  
 A txtUML model is a package with A txtUML model is a package with
-  * either a ''​package-info.java''​ file (in case of JtxtUML), where the package has an annotation of the form ''​@Model("​ModelName"​)''​((Fully qualified name: ''​hu.elte.txtuml.api.model.Model''​)) ​annotation,+  * either a ''​package-info.java''​ file (in case of JtxtUML), where the package has an annotation of the form ''​@Model("​ModelName"​)''​((Fully qualified name: ''​hu.elte.txtuml.api.model.Model''​)),​
   * or a ''​package-info.xtxtuml''​ file (in case of XtxtUML), which has a model declaration of the form ''​model-package example.x.model as "​ModelName";''​.   * or a ''​package-info.xtxtuml''​ file (in case of XtxtUML), which has a model declaration of the form ''​model-package example.x.model as "​ModelName";''​.
 All files in this package (and its subpackages) are part of the model. The wizard described above creates one of these files depending on the XtxtUML/​JtxtUML selection. All files in this package (and its subpackages) are part of the model. The wizard described above creates one of these files depending on the XtxtUML/​JtxtUML selection.
Line 60: Line 60:
  
 For JtxtUML syntax, select ''​File''​ / ''​New''​ / ''​Class''​ to create a new Java class. For JtxtUML syntax, select ''​File''​ / ''​New''​ / ''​Class''​ to create a new Java class.
- 
-See the [[v070:​language|Language Guide]] for the syntax of the different model elements in JtxtUML and XtxtUML. 
  
 ---- ----
Line 67: Line 65:
 ==== Modeling language ==== ==== Modeling language ====
  
-See the [[v070:language|Language ​Guide]] to study the txtUML language both in Java syntax (JtxtUML) and in custom syntax (XtxtUML). In case of JtxtUML, the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v070/​api/​java/​|JavaDoc]] of the API can also be used.+See the [[v070:modeling|Modeling ​Language ​Description]] to study the txtUML language both in Java syntax (JtxtUML) and in custom syntax (XtxtUML). In case of JtxtUML, the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v070/​api/​java/​|JavaDoc]] of the API can also be used.
  
 ---- ----
Line 77: Line 75:
 Currently class and state machine diagrams can be generated. Content and layout of the class diagrams and flat state machine diagrams can be defined by textual diagram descriptions. (Support for [[https://​github.com/​ELTE-Soft/​txtUML/​issues/​214|hierarchical diagrams]] is coming in a later release.) Currently class and state machine diagrams can be generated. Content and layout of the class diagrams and flat state machine diagrams can be defined by textual diagram descriptions. (Support for [[https://​github.com/​ELTE-Soft/​txtUML/​issues/​214|hierarchical diagrams]] is coming in a later release.)
  
-The following simple example assumes classes ''​A'',​ ''​B'',​ ''​C''​ and ''​D''​ in the model. We create a class diagram where classes ''​A'',​ ''​B''​ and ''​C''​ are in a row, and class ''​D''​ is below ''​B''​. Diagram definitions can be written using a Java API. See the [[v070:layout|Diagram Language ​Guide]] for a detailed description.+The following simple example assumes classes ''​A'',​ ''​B'',​ ''​C''​ and ''​D''​ in the model. We create a class diagram where classes ''​A'',​ ''​B''​ and ''​C''​ are in a row, and class ''​D''​ is below ''​B''​. Diagram definitions can be written using a Java API. See the [[v070:diagrams|Diagram Language ​Description]] for a comprehensive guide.
  
 Our example diagram can be defined as follows: Our example diagram can be defined as follows:
Line 149: Line 147:
 === Executing models === === Executing models ===
  
-txtUML models can be run as Java applications. The simplest way to run a txtUML model is to implement the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v070/​api/​java/​hu/​elte/​txtuml/​api/​model/​execution/​Execution.html|Execution]] interface, whose sole abstract method can be used as the ''​initialization()''​ of the model execution. That is, it should contain the model code which creates, links and starts the model class instances ​which should exist at the beginning of the execution.+txtUML models can be run as Java applications. The simplest way to run a txtUML model is to implement the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v070/​api/​java/​hu/​elte/​txtuml/​api/​model/​execution/​Execution.html|Execution]] interface, whose sole abstract method can be used as the ''​initialization()''​ of the model execution. That is, it should contain the model code which creates, links and starts the model class instances ​that should exist at the beginning of the execution.
  
 After the ''​initialization()''​ method is implemented,​ there are three possible ways to run the execution: After the ''​initialization()''​ method is implemented,​ there are three possible ways to run the execution:
Line 270: Line 268:
 {{v070:​DiagramAnimationPorts.png}} {{v070:​DiagramAnimationPorts.png}}
  
-Copy the //HTTP port// number into the //​Diagnostics port// input in your browser.+Copy the //HTTP port// number into the //​Diagnostics port// input in your browser ​and switch on diagnostics.
  
 {{v070:​DiagramAnimation.png}} {{v070:​DiagramAnimation.png}}
Line 288: Line 286:
 ==== Testing with sequence diagrams ==== ==== Testing with sequence diagrams ====
  
-See the [[v070:layout#​sequence_diagrams|Sequence Diagram Language ​Guide]] to study how to define sequence diagrams.+See the [[v070:diagrams#​sequence_diagrams|Sequence Diagram Language ​Description]] to study how to define sequence diagrams.
  
 txtUML models can be tested with sequence diagrams. You can run the model in parallel with a sequence diagram and check if the signals in the model are being sent in the same order you specified on the diagram. You can also assert states of the model objects. txtUML models can be tested with sequence diagrams. You can run the model in parallel with a sequence diagram and check if the signals in the model are being sent in the same order you specified on the diagram. You can also assert states of the model objects.
Line 371: Line 369:
  
 To generate C++ code from a txtUML model, you have to define a //​deployment configuration//​. A deployment configuration is a description of how model objects will be distributed across different threads. To generate C++ code from a txtUML model, you have to define a //​deployment configuration//​. A deployment configuration is a description of how model objects will be distributed across different threads.
-The deployment configuration is a special class which is derived from the ''​Configuration'' ​base class. ​+The deployment configuration is a special class which is derived from the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v070/​api/​java/​hu/​elte/​txtuml/​api/​deployment/​Configuration.html|Configuration]] ​base class. ​
 The model classes can be grouped together and these groups can be configured as described below. ​ The model classes can be grouped together and these groups can be configured as described below. ​
 The events that arrive for classes which belong to the same group will be served by a configured thread pool. The events that arrive for classes which belong to the same group will be served by a configured thread pool.
Line 381: Line 379:
   * ''​max'':​ It determines how many threads will be created at most. It must be a natural number. Its default value is determined by the value of ''​constant''​.   * ''​max'':​ It determines how many threads will be created at most. It must be a natural number. Its default value is determined by the value of ''​constant''​.
  
-If there are classes ​with no groups aligned ​to them, a default implicit group will be created which contains these classes. It will be configured with the default values shown above. ​+If there are classes ​without a group assigned ​to them, a default implicit group will be created which contains ​all of these classes. It will be configured with the default values shown above. Please note, however, that – due to technical limitations – a configuration should contain at least one group definition with at least one class in it. 
 + 
 +Additionally,​ you can specify whether you want the exported model to be executed by a single threaded runtime instead of the default multithreaded one. This can be achieved by placing the ''​@Runtime(RuntimeType.SINGLE)''​ annotation on the configuration class. In this case, grouping is effectively ignored.
  
 === Configuration examples === === Configuration examples ===
  
 <code java> <code java>
-class DefaultConfiguration ​extends Configuration {}+@Runtime(RuntimeType.SINGLE) 
 +@Group(contains = {A.class}) 
 +class ExampleConfiguration ​extends Configuration {}
 </​code>​ </​code>​
  
-This means that all of the classes ​will be grouped ​in the default group.+This means that the single threaded runtime ​will be used. Here, grouping has no effect, but we defined one group with a class in it nevertheless,​ as this is currently required due to technical limitations.
  
 <code java> <code java>
Line 397: Line 399:
 </​code>​ </​code>​
  
-This means that instances ​of classes ''​A''​ and ''​B''​ are served by the same thread pool, which contains two constant threads plus one for every ''​2''​ ''​A''​ or ''​B''​ instances created, but no more than ''​10''​. Instances of class ''​C''​ are served by another thread pool and it contains only one thread (according to the default values).+In this example, the default multithreaded runtime is used. Instances ​of classes ''​A''​ and ''​B''​ are served by the same thread pool, which contains two constant threads plus one for every ''​2''​ ''​A''​ or ''​B''​ instances created, but no more than ''​10''​. Instances of class ''​C''​ are served by another thread pool and it contains only one thread (according to the default values).
  
 We suggest reviewing the deployment configurations in the {{v070:​demo.zip|demo projects}}. We suggest reviewing the deployment configurations in the {{v070:​demo.zip|demo projects}}.
Line 428: Line 430:
 Compiling the exported C++ files can be achieved in multiple ways. Compiling the exported C++ files can be achieved in multiple ways.
  
-  * If you select ​specific build environments during the code generation phase, you can conveniently use these environments on the automatically prepared files placed in the //build_// prefixed output folders.+  * If you selected ​specific build environments during the code generation phase, you can conveniently use these environments on the automatically prepared files placed in the //build_// prefixed output folders.
   * Using the generated //​CMakeLists//​ file, you can create these environment-specific "make files" manually, which then you can feed to the chosen build environments.   * Using the generated //​CMakeLists//​ file, you can create these environment-specific "make files" manually, which then you can feed to the chosen build environments.
   * If all else fails, you can also build from the generated files with any C++ compiler manually.   * If all else fails, you can also build from the generated files with any C++ compiler manually.
Line 460: Line 462:
 In the following we present concrete usage examples, but you can also consult the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v070/​api/​cpp/​|C++ Runtime API documentation]] and the //​main.cpp//​ files provided with the {{v070:​demo.zip|demo models}}. In the following we present concrete usage examples, but you can also consult the [[http://​txtuml.inf.elte.hu/​releases/​txtuml-v070/​api/​cpp/​|C++ Runtime API documentation]] and the //​main.cpp//​ files provided with the {{v070:​demo.zip|demo models}}.
  
-**Warning!** When the generated model is used by an external component, the model objects should be allocated on the heap. The reason for this is that objects can be deallocated inside the model. Please note that //​main.cpp//​ files provided with the demo models only allocate objects in the stack to keep the examples as simple as possible – the place of allocation should be considered carefully in real-life projects.+**Warning!** When the generated model is used by an external component, the model objects should be allocated on the heap. The reason for this is that externally created ​objects can be deallocated inside the model. Please note that the //​main.cpp//​ files provided with the demo models only allocate objects in the stack to keep the examples as simple as possible – the place of allocation should be considered carefully in real-life projects.
  
 == Referring to exported entities == == Referring to exported entities ==
  
-The fully qualified names of source model entities are flattened into namespace ''​Model''​ in the exported files. For example, a source model class named ''​A''​ should be referred to as ''​Model::​A'',​ regardless of its original fully qualified name. Depending on the kind of the source element, referencing can be done in the following ​way:+The fully qualified names of source model entities are flattened into namespace ''​Model''​ in the exported files. For example, a source model class named ''​A''​ should be referred to as ''​Model::​A'',​ regardless of its original fully qualified name. Depending on the kind of the source element, referencing can be done in the following ​ways:
  
   * **Classes:​** A source class named ''​A''​ can be referred to as ''​Model::​A''​ in the execution initialization function. In this case, //A.hpp// has to be included.   * **Classes:​** A source class named ''​A''​ can be referred to as ''​Model::​A''​ in the execution initialization function. In this case, //A.hpp// has to be included.
-  * **Ports:** A source port named ''​A.P''​ on class instance ''​a''​ can be referred to as ''​a->P''​ in the execution initialization function. In this case, //A.hpp// has to be included.+  * **Ports:** A source port named ''​A.P''​ on class instance ''​a''​ can be referred to as ''​a.P''​ in the execution initialization function. In this case, //A.hpp// has to be included.
   * **Signals:​** An instance of a signal named ''​S''​ can be referred to / constructed as ''​Model::​SPtr(new Model::​S_EC(<​ctor args>​))''​ in the execution initialization function. In this case, //​EventStructures.hpp//​ has to be included.   * **Signals:​** An instance of a signal named ''​S''​ can be referred to / constructed as ''​Model::​SPtr(new Model::​S_EC(<​ctor args>​))''​ in the execution initialization function. In this case, //​EventStructures.hpp//​ has to be included.
   * **Association,​ composition and connector ends**: A source association/​composition/​connector end named ''​A.e''​ can be referred to as ''​Model::​A.e''​ in the execution initialization function. In this case, //​AssociationInstances.hpp//​ has to be included.   * **Association,​ composition and connector ends**: A source association/​composition/​connector end named ''​A.e''​ can be referred to as ''​Model::​A.e''​ in the execution initialization function. In this case, //​AssociationInstances.hpp//​ has to be included.
Line 473: Line 475:
 == Action language == == Action language ==
  
-The action language provided in C++ is analogous to the original Java version (see [[v070:language#Action code]] for more detailed semantics). To use the ''​Action::''​-prefixed language elements below, you have to include //​runtime/​Action.hpp//​.+The action language provided in C++ is analogous to the original Java version (see [[v070:modeling#Action code]] for more detailed semantics). To use the ''​Action::''​-prefixed language elements below, you have to include //​runtime/​Action.hpp//​.
  
 <code cpp> <code cpp>
Line 488: Line 490:
  
 <code cpp> <code cpp>
-Action::​link(AB.a, ​objA, AB.b, objB);+Action::​link(AB.a, ​instanceOfA, AB.b, instanceOfB);
 </​code>​ </​code>​
  
 <code cpp> <code cpp>
-MultipliedElement<​B,​ 0, -1> ​objBs a.assoc(AB.b);​+MultipliedElement<​B,​ 0, -1> ​bs instanceOfA.assoc(AB.b);​
   // MultipliedElement<​T,​ L, U> means:   // MultipliedElement<​T,​ L, U> means:
   //   a collection of Ts with multiplicity L..U   //   a collection of Ts with multiplicity L..U
Line 500: Line 502:
  
 <code cpp> <code cpp>
-// include '​runtime/​PortUtils.hpp'​ for direct use +delegateConnect(instanceOfA.PortAP, Conn.bpeinstanceOfB.PortBP); 
-delegateConnect(objA.PortAP, Conn.bpobjB.PortBP); +assemblyConnect(Conn.apeinstanceOfA.PortAP, Conn.bpeinstanceOfB.PortBP); 
-assemblyConnect(Conn.apobjA.PortAP, Conn.bpobjB.PortBP);+  // include '​runtime/​PortUtils.hpp'​ for direct use
 </​code>​ </​code>​
v070/userguide.txt · Last modified: 2018/10/08 22:31 by djnemeth