Xholon with MagicDraw HelloWorld Tutorial

How to create a MagicDraw model that can be transformed to a Xholon app

This describes how to create a model using MagicDraw (tested with version 10.0 and 11.5) that can be executed using the Xholon runtime framework. The model will be converted from XMI to the Xholon XML and Java format, and will then be executed using the Xholon runtime framework. The last page is a set of issues.

Start up MagicDraw (www.magicdraw.com). Create a new project (File --> New Project), and name the project HelloWorldTutorial. Also name the model (the root of the Containment Tree) HelloWorldTutorial.

HeloWorld MagicDraw inheritance hierarchy

XholonClass

Create a root class owned by the HelloWorldTutorial model. To do this, right-click HelloWorldTutorial, select New Element --> Class. Name it XholonClass. Set the following properties by selecting XholonClass and pressing the Enter key to open its specification.

  • Base Classifier: EncapsulatedClassifier from the UML Standard Profile::UML 2.0 Metamodel::CompositeStructures::Ports package.
  • Applied Stereotype: PureContainer
  • Visibility: public (this is the default)
  • IsActive: false, IsAbstract: true

Create stereotypes called PureActiveObject and PureContainer. The stereotypes can be created by selecting Applied Stereotype in the class's Properties pane. These stereotypes will have Metaclass=Class.

Create a package called HelloWorldTutorial. To do this, right-click the HelloWorldTutorial model icon, select New Element --> Package, and name it HelloWorldTutorial.

Create a class diagram that can be used to create classes. To do this, right-click the HelloWorldTutorial package icon, select New Diagram --> Class Diagram, and name it InheritanceHierarchy. The new class diagram should open up in MagicDraw.

Drag the XholonClass class from the browser to the diagram.

Create three classes within the new HelloWorldTutorial package. It's easiest to do this by clicking the Class symbol in the class diagram menu, and then clicking within the diagram itself. Name the three new classes as follows:

HelloWorldSystem

Hello

World

  • Base Classifier for all three: XholonClass, so they can own Ports. You can do this by selecting the Generalization icon from the class diagram menu, clicking on the class, dragging until the cursor is over XholonClass, and then releasing the mouse button.
  • Applied Stereotype for Hello and World: PureActiveObject

Make sure that the three new classes are within the HelloWorldTutorial package. If they are not, drag them inside using the MagicDraw tree browser. XholonClass should remain within the HelloWorldTutorial model rather than within the package.

Create a Signal class within the HelloWorldTutorial package. Do this by clicking the small triangle next to the Class symbol in the class diagram menu. Click the Signal icon that will appear in the menu. Call the new Signal class SIGNAL_ONE. Open the specification for the Signal. Select Attributes in the tree browser on the left, and then press the Create button. Enter the value 100 as the Default Value, set Is Read Only to true, and set Visibility to public. No other fields need to be set. The attribute should not have a Name. To set the Is Read Only property, you may need to make it visible by first selecting Properties: Expert near the top of the specification window. Press the Close button. To make the attribute visible in the class diagram, right-click the new Signal class and unselect Presentation Options --> Suppress Attributes.

Create an Interface within the HelloWorldTutorial package. Do this by clicking the Interface symbol in the class diagram menu. Name the interface IHwIn. Open the specification for the Interface. Select Attributes in the tree browser on the left, and then press the Create button. The new attribute should have a Visibility of public, should have no Name, should have a Type of SIGNAL_ONE (the Signal class created above), should have Is Read Only = true and Is Static = true. To make the attribute visible in the class diagram, right-click the new Signal class and unselect Presentation Options --> Suppress Attributes. (see note at end of this document re signals as attributes of an Interface rather than as operations)

Create a second Interface called IHwOut. It should have the same attribute as for the IHwIn interface.

Create a Port class within the HelloWorldTutorial package, using the class diagram. Create a normal Class called Partner, and then open its specification.

Partner

  • Base Classifier: Port from the UML Standard Profile::UML 2.0 Metamodel::CompositeStructures::Ports package.
  • Add an attribute with a default value of 0. Don't give the attribute a Name or a Type. To create the default value, right-click the Default Value field, select Value Specification --> Literal Integer, and then type in the number 0. Open the specification for this attribute, and set:
  • - Visibility: public
  • - Is Read Only: true
  • - Is Static: true
  • In Java, this is equivalent to:
  • public static final int Partner = 0;

Select Interface Realization from the Class diagram menu. Click on the Partner class, drag the line to the IHwIn interface, and release the mouse button. Select Usage from the Class diagram menu. Click on the Partner class, drag the line to the IHwOut interface, and release the mouse button. This specifies that IHwIn is a provided interface for the Partner port class (note the full circle icon), and that IHwOut is a required interface for the Partner port class (note the half-circle icon). In this simple example, the provided and required interfaces each have one and the same signal. A Partner port is symmetrical. It allows the same signal type (SIGNAL_ONE) to be sent in both directions.

Create a composite structure in which HelloWorldSystem contains two parts, Hello and World. Hello and World will each have one port. These two ports will be connected using a connector.

To do this, in the Containment Tree browser, right-click the HelloWorldSystem class. Select New Diagram --> Composite Structure Diagram. Name this diagram CompositeStructure.

Within the new diagram, select the Classifier icon, select HelloWorldSystem from the pop-up, press the OK button, and create a rectangle in the diagram representing this class.

Select the Part icon, move the cursor over the HelloWorldSystem rectangle, click, select Hello, and press the OK button.

Select the Part icon, move the cursor over the HelloWorldSystem rectangle, click, select World, and press the OK button.

Select the Port icon, move the cursor over the Hello rectangle, click, select Partner as Type, and click OK. Create a similar Port for World.

Click on each of these new ports in the diagram, press Enter to open its specification, and set its properties as follows:

  • Name: use any name you want, or leave the name blank
  • IsService: false (Hello), true (World)
  • IsBehavior: true

Optionally, right-click on each of these ports, and select Show Type.

Click on the Connector icon, move the cursor over the Hello Partner port, click, drag the cursor to the World Partner port, and click again. Make sure that you click while over the port and not while over the part that owns the part. Open the specification for the connector, and confirm that Kind has the value assembly.

You should now have a diagram that looks like the following:

HelloWorld MagicDraw - composite structure

State Machines

Add a state machine to Hello.

To do this, in the Containment Tree browser, right-click Hello, select New Diagram --> State Machine Diagram, and name it StateMachine_Hello. This will create a State Machine Diagram within a State Machine.

Within the new state diagram, create a Composite State, and put an Initial pseudostate and State inside, as shown in the following diagram. Name the state SayingHello. Draw an initial Transition from the Initial pseudostate to the SayingHello state. Also draw a self transition on the SayingHello state. You can do this using either the Transition to Self tool, or as a regular Transition that starts and ends in the same state.

HelloWorld MagicDraw - Hello FSM

Click on the initial transition and press the Enter key to bring up its specification. Leave the Name blank.

  • Effect --> Behavior Type: Activity

Find this new activity in the Containment Tree browser, and select the Documentation tab in the lower left window. Enter the following two lines of Java code, to ensure that Hello will initiate a series of back and forth messages between itself and World when the model executes:

print("{Hello "); port[Partner].sendMessage(SIGNAL_ONE, null, this);

Click on the self transition in the state diagram, and press the Enter key.

  • Name: CNPT_OUTGOING1 (name must end with the digit 1)
  • Trigger --> EventType: SignalEvent
  • Trigger --> Signal: SIGNAL_ONE
  • Effect --> Behavior Type: Activity

Find this second new activity in the Containment Tree browser, and again select the Documentation tab in the lower left window. Enter the following two lines of code:

print("{Hello "); port[Partner].sendMessage(SIGNAL_ONE, null, this);

Add a similar state machine to World. The only differences are that the state is called SayingWorld, and that there is no Activity and therefore no code associated with the initial transition.

HelloWorld MagicDraw - World FSM

Enter the following two lines of code in the World self transition (in the Documentation tab for the Activity associated with that transition):

println("World}"); port[Partner].sendMessage(SIGNAL_ONE, null, this);

Save the MagicDraw model in mdzip format, to the Xholon/transform/MagicDraw directory. This is the default MagicDraw format, a zipped XMI 2.1 file.

How to transform the MagicDraw model into a Xholon application

If you are using Microsoft Windows, open a console window. Change to the Xholon/transform/MagicDraw directory. Run the following command:

xmi2xh all HelloWorldTutorial HelloWorldSystem (if using Windows/DOS) ./xmi2xh all HelloWorldTutorial HelloWorldSystem (if using Linux/Unix)

For detailed information see _README.txt in the MagicDraw directory. You will need a third-party XSLT tool to be able to run the xmi2xh script. The result should look similar to the following:

Unzipping HelloWorldTutorial.mdzip ... Extracting: HelloWorldTutorial.mdxml creating InheritanceHierarchy XML file ... creating ClassEnum Java file ... creating CompositeStructureHierarchy XML file ... creating ClassDetails XML file ... creating Xh Java file ... creating App Java file ... creating Information XML file ... creating _xhn XML file ...

The three Java files are generated in the Xholon\src\org\primordion\xholon\xmiapps directory. The five XML files are generated in Xholon\config\xmiapps\HelloWorldTutorial.

How to execute the generated Xholon application

Compile the generated Java files - AppHelloWorldTutorial.java, XhHelloWorldTutorial.java, and CeHelloWorldTutorial.java.

Execute the application from the command line or using the Xholon GUI, as described in README.txt in the Xholon root directory. To use the Xholon GUI, change to the root Xholon directory, enter xhn Xholon (Windows/DOS) or ./xhn Xholon (Linux/Unix). From the GUI menu, select File --> Open --> xmiapps --> HelloWorldTutorial --> HelloWorldTutorial_xhn.xml and press the Open button. Select Controller --> Start. You should see the following output in the console window:

{Hello World} {Hello World} {Hello World} {Hello World} {Hello World} {Hello

Notes/Issues

  • This tutorial implies that signals are attributes of an Interface. UML2 specifies that they should be operations. For practical purposes, Xholon expects them to be attributes. This needs to be thought through in more detail.
  • All of the classes are IsActive = false. Hello and World are Xholon active objects and could be IsActive = true. Is there any practical advantage to doing this? UML2 defines "active object" as an object that has its own thread of control (UML Superstructure document, version 2, formal/05-07-04). Xholon active objects may or may not fit the UML2 definition.
  • Should I use the PureActiveObject stereotype, or the fact that a class has behavior, or both, to determine whether a Xholon class is a PureActiveObject type?
  • There is no explicit way to have Java code on a transition in MagicDraw, so I'm using the Activity Documentation for now.
  • It seems there is no need to create separate Composite Structure Diagrams for Hello and World, because they have no internal parts, and the ports can be added from within the Composite Structure Diagram for HelloWorldSystem. But it might be good style to create these separate diagrams.
  • There doesn't seem to be any way to specify which port a SignalEvent is associated with when creating an event trigger. This is crucial if there are more than one port that can receive messages with the same signal. This has to be done using a Guard on the transition.
  • Transition names don't appear on the state diagram next to the transition. The only label that shows up is the Signal name, which is maybe the correct choice. But initially, when first creating a state diagram, all I typically have are names, and I may not have decided what event will be triggering that transition yet.