User Tools

Site Tools


v050:userguide

This is an old revision of the document!


User Guide for version 0.5.0

Release notes, reporting bugs

Installation

Sample models

For a quick start we recommend experimenting with the sample models.

  • Download and unzip the sample models.
  • Import them into your Eclipse workspace (File / Import / General / Existing projects into workspace).

Sample models are implemented using either XtxtUML syntax (see the source packages <name of example>.x.model) or JtxtUML syntax (see the source packages <name of example>.j.model), or both. In addition, the sample models are accompanied with diagram descriptions (see the Java classes inheriting from the ClassDiagram, StateMachineDiagram or CompositeDiagram type).

We suggest reading the Generating diagrams and the Running and debugging models sections as the next steps of experimenting with the sample models.

Creating own models

New txtUML project

txtUML models should be placed in txtUML projects. A new txtUML project can be created by selecting File / New project… / txtUML / txtUML Project and setting the project name.

By default, the project will be created in the current workspace. In order to override this, uncheck the Use default location checkbox and select a location for the new project.

New txtUML model

Select File / New / Other… / txtUML / txtUML Model.

Select a Source folder from an existing project for the new model. Select an existing Package from that folder or type a new Package name. Type a Name for the new model.

Select the syntax of the new model:

  • XtxtUML for custom modelling 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.

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”)1) annotation,
  • 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.

New model elements

For XtxtUML syntax, select File / New / Other… / txtUML / XtxtUML File. Fill in the source folder and package to place the new source file in, then enter a file name. You can also choose between the two possible extensions: .xtxtuml or .txtuml.

For JtxtUML syntax, select File / New / Class to create a new Java class.

See the Language Guide for the syntax of the different model elements in JtxtUML and XtxtUML.

Modeling Language

See the Language Guide to study the txtUML language both in Java syntax (JtxtUML) and in custom syntax (XtxtUML). In case of JtxtUML, the JavaDoc of the API can also be used.

Generating diagrams

It is possible to generate EMF-UML2 models together with Papyrus diagrams from txtUML models. Currently class, state machine and composite structure diagrams can be generated. Content and layout of the class diagrams and flat state machine or composite structure diagrams can be defined by textual diagram descriptions. (Support for 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 with 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 Diagram Language Guide for detailed description.

Our example diagram can be defined as follows:

public class ExampleDiagram extends ClassDiagram {
	@Row({A.class, B.class, C.class})
	@Below(val = D.class, from = B.class)
	class ExampleLayout extends Layout {}
}

In order to generate diagrams, from the menu select txtUML / Generate diagrams from txtUML.

Fill in the name of the project containing the txtUML model, then the fully qualified name of the model. Using the Add txtUML diagram description button, you can add as many diagram descriptions as needed. In our example, there is only one. The fully qualified name of the Java class representing the diagram definition needs to be filled in.

When clicking Finish, a Papyrus model is generated with the following class diagram:

Diagram language

See the Diagram Language Guide for detailed description of the diagram language of txtUML.

Running and debugging models

The following hold both for XtxtUML and JtxtUML.

Switch to Java or Debug perspective and create a new run/debug configuration. Use Java Application type if you only want to run or debug the model only in text. Use txtUML Application type if state machine animation is required as well.

Breakpoints can be created and managed the same way as for Java programs. The standard debug controls (stop, pause, resume, step, step-into) work as usual.

The variable view can show the current signal, current state, associations and the attribute values of the actual object.

State machine animation

txtUML can animate state machine diagrams generated by the txtUML visualization process. See the Generating diagrams section. Make sure that the run/debug configuration is of txtUML Application type.

Open the generated Papyrus diagram and start the model either in run or in debug mode. The current state and currently executed transition gets highlighted.

For each state machine diagram, the state changes of the first activated object of the corresponding type will be highlighted. An expected later improvement will make it possible to select the object to be animated during the debug session.

Compilation to C++

The C++ model compiler can be reached by selecting the txtUML / Generate C++ code from txtUML menu.

The Eclipse project and the package that contains the model must be specified. The runtime library contains only pre-written cpp files so they can be used for other generated models too.

The txtUML deployment configuration is a description of how the object instances will be distributed into different threads. The deployment configuration is a special class which is derived from Configuration base class. 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.

You can group by the help of Group annotation which contains the following configuration options:

  • contains: You can enumerate the classes which belongs to this group.
  • constant: It determines how many threads will be regardless of the number of object instances. It's default value is 1. It must be a natural number.
  • gradient: It determines how many threads will be created depending on the number of objects. It can be a real number between 0.0 and 1.0. It is a linear dependency. (value * n - where n is the number of created objects). It's default value is 0.
  • max: It determines how many threads will be created at most. It's default value is determined by the value of constant.

If there are classes with no groups aligned to them then a default implicit group will be created which contains these classes. It will be configured with the default values shown above.

Examples:

class DefaultConfiguration extends Configuration {}

This means that all of the classes will be grouped to the default group.

@Group(contains = {A.class, B.class}, max = 10, constant = 2, gradient = 0.5)
@Group(contains = {C.class})
class ExampleConfiguration extends Configuration {}

This means that A and B objects instances are served by the same thread pool witch contains two constant threads plus one for every 2 A or B typed objects created, but only 10 at most. The C typed objects are served by another thread pool and it contains only one thread (default values).

We suggest reviewing the deployment configurations in the demo projects.

The generated C++ code is saved in the cpp-gen folder of the selected project. Note that you might have to refresh the folder so that the newly generated files become visible in Eclipse.

CMake support:

You can compile the generated files with any C++ compiler manually but we suggest using the generated CMakelist file to create native “make files” that can be used in the compiler environment of your choice. Cmake is available from https://cmake.org/. You should create a new folder next to the generated files where the build environment should be created. Open a terminal or command prompt and type the following command:

cmake -G "Chosen build enviorement" -D CMAKE_BUILD_TYPE=[Bedug,Relase] [.,..]
(it depends on where the CMakeList file is compared to the current path)

The cmake –help command listing the possible build enviroments.

1) Fully qualified name: hu.elte.txtuml.api.model.Model
v050/userguide.1469692452.txt.gz · Last modified: 2016/07/28 09:54 by ndj94