xUML-RT Model Executor v0.4.0 (2015-07-03)

Features

Changes

New features:

• Static class modeling without action code support:
  • Attributes with primitive types
  • Operations with parameters
  • Signal data
  • Associations
  • Multiplicities
• Communication with external entities

Installation instructions

Eclipse interface

• Supported Eclipse version is 4.4 (Luna).
• Update site for this particular release: http://modelexecution.eltesoft.hu/update/20150703/
• Update site of the latest release (recommended): http://modelexecution.eltesoft.hu/update/latest/
• Note: If you have IncQuery or XText installed, please make sure that IncQuery version is smaller than 0.9.0 and XText version is smaller than 2.7.0. Model executor currently uses earlier versions and the Elipse installation procedure cannot downgrade and will fail. If you do not have these software components, the correct versions will be installed automatically as part of the installation process.

Command line interface

• Download this jar file.

Using the xUML-RT Model Executor

Eclipse interface

• Make sure that you have JRE 1.8 configured in Eclipse.
• Create a new project of type xUML-RT Project. (This can be found in the Papyrus category if Papyrus is installed and in the Other category otherwise.)
• Add a new EMF-UML2 model (or copy an existing one) to the project. Note that the current version supports simple models like these.
  Note: It is advised to use only one model in the project.
• Create a new run configuration of type xUML-RT Executor. Select the model, the class and the entry operation.
• Open the state machine diagram in Papyrus.
• Debug the newly created launch configuration and see the animation on the state machine and the console log.
• Moka animation controls and breakpoints on states and transitions are supported.

Command line interface

• Ask for all supported options:
  java -jar xumlrt-executor-cli.jar --help
• Setup a model for execution:
  java -jar xumlrt-executor-cli.jar --root gen --setup model.uml
  Note: Use java from a JDK in order to ensure successful compilation of the generated Java files.
• Execute the model:
  java -jar xumlrt-executor-cli.jar --root gen --execute ClassName opName --logger minimal

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»

• The class name must be a Java identifier.
• The class must be abstract.
• It must not have any attribute.
• The implementation class name referenced in the class stereotype attribute must be a Fully qualified Java class name.
• Only non-static operations are allowed.
• All operation names must be valid Java identifiers.
• An operation could have at most one parameter.

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

• It is an input parameter.
• The parameter name is a Java identifier.
• Multiplicity of the parameter is one ([1..1]).
• The type of the parameter is a class which is marked with the «callable» stereotype.

Constraints on classes marked with «callable»

• The class name must be a Java identifier.
• All reception names must be Java identifiers.