Installation instructions

Eclipse interface

Command line interface

Tutorial

Eclipse interface

Make sure that you have JRE 1.8 configured in Eclipse.

Quick start

You can use an example wizard to add an example project with demo models into your workspace.
  1. Select File | New | Example... | xUML-RT Examples > xUML-RT State Machine Examples
  2. Click Next.
  3. Click Finish.
  4. Open any of the models in the newly created xUML-RTExamples project
  5. Open the state machine diagram in Papyrus.
  6. Debug the corresponding pre-created launch configuration and see the animation on the state machine and the console log.
  7. You can add breakpoints to the state machines by right clicking a state or transition on the diagram (or in the model explorer), then selecting Moka > Debug > Toggle breakpoint.
  8. Standard debug controls of the Debug view (pause, step, resume, stop) are supported.

Own project

  1. Create a new project of type xUML-RT Project.
    1. In Project Explorer select New | Project... | Papyrus > xUML-RT Project
    2. Set project name
    3. Press the Finish button.
  2. Add a new EMF-UML2 model (or copy an existing one) to the project. Note that the current version supports simple models like these. In order to execute a model you need to implement a feed function which contains action code that makes your model move (e.g. sends signals).
  3. Create a new run configuration of type xUML-RT Executor. Select the model, the class and the entry operation.
    1. Select Run | Debug Configurations... | xUML-RT Executor | New
    2. Set the following:
      • Name of the configuration
      • Set Select model: the .uml file of the model
      • Set Select class: class containing an operation that shall be called to run the model
      • Set Select feed function: the operation of the selected class to be called
  4. Open the state machine diagram in Papyrus.
  5. Debug the newly created launch configuration and see the animation on the state machine and the console log.
  6. You can add breakpoints to the state machines by right clicking a state or transition on the diagram (or in the model explorer), then selecting Moka > Debug > Toggle breakpoint.
  7. Standard debug controls of the Debug view (pause, step, resume, stop) are supported.

Command line interface

External communication

Beginning with release 0.4.0 Model executor supports calling external Java classes, i.e. a Java classes which are not part of the executable model. The implementation is based on the introduction of external entities.

From the model's point of view, an external entity is an abstract class marked with the «externalEntity» stereotype. These classes must have only non-static methods, which will be implemented by external Java classes. When an external entity method is called from the action code in the model, the call will be dispatched to an instance of the selected Java class. The fully qualified name of the implementation class must be provided as an attribute of the stereotype. By default a new instance will be created by the executor every time it dispatches an external entity method call. It is also possible to configure an external entity to create a lazy singleton, which will be instantiated at the first method call. Then every other invocations will use the same Java class instance of that external entity. This behavior can also be specified a stereotype attribute. Using the «externalEntity» stereotype on a class will add several constraints to its validation process, which are described in a separate section below. These constraints are ensuring that a valid Java interface could be generated from the external entity definition. The implementation class of an external entity then must implement its generated interface.

It is also possible to send events to the state machine of an active class from an external entity, which enables two-way communication with native code. Active classes which are able to receive events from external entities through receptions must be marked with the «callable» stereotype. Then for each callable class a Java proxy class will be generated. An external entity method then could have at most one parameter. When it is present, it must be an input parameter, which is typed as a «callable» class. The external entity implementation could use this reference to call the appropriate receptions on the active class instance. Validation of callable classes is also constrained to ensure the class name and the reception names are valid Java identifiers. For more information on constraints, see their separate section below.

Steps to create an external entity with a callable active class

  1. Apply the xUML-RT registered profile on the model root. This could be done from its properties view, under the Profile tab.
  2. Create a class which has a state machine as its owned behavior.
  3. If the external entity will send signals to the state machine, apply the «callable» stereotype on the class. Stereotype applications could also be done under the Profile tab on the properties view of the selected element.
  4. Add the required receptions to the class according to the naming constraints below. These will be accessible from external entities to send events for a state machine instance.
  5. Create an abstract class for an external entity according to the constraints below, and apply the «externalEntity» stereotype on it.
  6. Specify the fully qualified Java implementation class name for the external entity with the class stereotype attribute.
  7. Select an instantiation policy using the type stereotype attribute. Stateless will dispatch every external entity method invocation to a new instance of the implementation class, while Singleton will use a single instance which will be created by the executor at the first method call.
  8. Add non-static methods to the external entity. These methods must not have any parameters if they don't send any event to any state machine.
  9. To implement two-way communication, create one or more methods in the external entity class which have a single parameter with input direction. The parameter must conform to the constraints detailed in the next section — so it must refer to a «callable» class instance.
  10. Implement the specified external entity class in Java. The simplest way is to extend the source path of the current xUML-RT project in its properties window with another source directory. It could be done under the Java Build Path / Source tab.
  11. The implementation class must be placed into this source directory, and have the same fully qualified name as it was specified earlier in the «externalEntity» stereotype's class attribute.
  12. When an xUML-RT project is being built, it generates a Java interface for each external entity with exactly the same name as its class name. Every implementation class must explicitly implement that generated Java interface. When a method refers to a callable class instance as its parameter, the receptions available could be invoked from Java through that reference.
  13. Call the external entity in your action code. The external entity operations could be referenced with the name of the entity and with the method name, separated by double colons (::). For example, when the external entity name is Entity, and the method name is method, the following statement could be used from action code: Entity::method();
  14. When the given external entity method supports two-way communication, the current «callable» class instance could be provided as a parameter to the call from the action code as Entity::method(this);

Stereotype constraints

The model must be explicitly validated to trigger these constraints. This could be requested for instance from the context menu on the model root in the Model Explorer view of Papyrus. The next concepts are used in the constraints below:

Java identifier
A string matching the regular expression [\p{L}_$][\p{L}\p{N}_$]*. It must start with a unicode letter or an underscore character, or either with a dollar sign. The follwoing characters could also contain numbers. A valid identifier must be at least one character long according to this constraint.
Fully qualified Java class name
Consists of a single or multiple Java identifiers, separated by dots.

Constraints on classes marked with «externalEntity»

If the optional parameter is present in the signature of an external entity operation, it must conform to the following constraints:

Constraints on classes marked with «callable»

Features

Classes

Inheritance

Events

Signals

State machines

Communication with external entities

Calling external Java classes, i.e. a Java classes which are not part of the executable model.