Tutorials

Tutorials

There will be one or more tutorials on how to use Xholon. Hello World is the first.

There is also a tutorial on using the MagicDraw UML tool to create a Xholon model.

There is also a tutorial on using the Topcased modeling tool to create a Xholon model.

Hello World Tutorial

In this very basic tutorial, you will learn how to create and execute a very simple Xholon model, without the use of any UML modeling tool. As your development environment, you can use Eclipse, another toolset, or a text editor and console window.

The model includes three classes as shown in the following UML 2.0 composite structure diagram.

Three Xholons in Hello World tutorial

Begin by creating a new subdirectory of config called MyHello.

Decide what classes will be used to model your application. Determine inheritance relationships between these classes. Create a file called InheritanceHierarchy.xml containing the following text. This is a tree with the inheritance hierarchy of the classes. The root of the inheritance hierarchy must be XholonClass.

<?xml version="1.0" encoding="UTF-8"?>
<XholonClass>
    <HelloWorldSystem/>
    <Hello/>
    <World/>
</XholonClass>

Specify the composite structure of Xholons within the system. Create a file called CompositeStructureHierarchy.xml containing the following text. This tree represents the desired containment hierarchy of the system. There will be one root level structured classifier called HelloWorldSystem, containing two parts, an instance of Hello and an instance of World.

<?xml version="1.0" encoding="UTF-8"?>
<HelloWorldSystem>
    <Hello/>
    <World/>
</HelloWorldSystem>

Define potential interactions between Xholons within the system, by specifying ports. Create a file called ClassDetails.xml containing the following text. Hello and World are both active objects with one port each. Each port is named P_PARTNER, although they could each have different names. The xpointer parentheses contain an XPath expression which tells each Xholon how to find its interaction partner. Hello is instructed to navigate up the composite structure tree until it finds a Xholon ancestor of class HelloWorldSystem, and then to look for a child of that node whose class is World. World likewise searches for a partner of class Hello. The last element in this file, <XholonClass .../>, specifies that all classes not specifically listed previously (including HelloWorldSystem) are considered to be pure containers, which means they will have no ports and will not be able to participate in interactions except with parents and children.

<?xml version="1.0" encoding="UTF-8"?>
<xholonClassDetails>
    <Hello xhType="XhtypePureActiveObject">
        <port name="port" index="P_PARTNER" connector="#xpointer(ancestor::HelloWorldSystem/World)"/>
    </Hello>
    <World xhType="XhtypePureActiveObject">
        <port name="port" index="P_PARTNER" connector="#xpointer(ancestor::HelloWorldSystem/Hello)"/>
    </World>
    <XholonClass xhType="XhtypePureContainer"/>
</xholonClassDetails>

Create a main configuration file called MyHello_xhn.xml containing the following XML text. The XML file names need to agree with the names you have used in the steps above. The executable will iterate through 10 process loops (time steps).

<?xml version="1.0" encoding="UTF-8"?>
<params>
    <param name="ShowParams" value="true"/>
    <param name="ModelName" value="My Hello World"/>
    <param name="AppM" value="true"/>
    <param name="InfoM" value="false"/>
    <param name="ErrorM" value="true"/>
    <param name="MaxProcessLoops" value="10"/>
    <param name="TimeStepInterval" value="10"/>
    <param name="SizeMessageQueue" value="1"/>
    <param name="InheritanceHierarchyFile" value="./config/MyHello/InheritanceHierarchy.xml"/>
    <param name="CompositeStructureHierarchyFile" value="./config/MyHello/CompositeStructureHierarchy.xml"/>
    <param name="ClassDetailsFile" value="./config/MyHello/ClassDetails.xml"/>
    <param name="InformationFile" value="./config/MyHello/Information.xml"/>
    <param name="JavaClassName" value="org.primordion.xholon.tutorials.AppMyHello"/>
    <param name="JavaXhClassName" value="org.primordion.xholon.tutorials.XhMyHello"/>
    <param name="MaxPorts" value="1"/>
</params>

You can optionally create a file called Information.xml containing information about your application. It must use specific XML tags, as shown in this example. This can be viewed at run-time by selecting Help --> Information from the GUI, or anytime simply by loading it into any web browser.

You will now need to create three Java files. Overall startup, configuration and control aspects of your application can be implemented by AppMyHello in the file AppMyHello.java. Click here to see what the result should look like. This file contains the Java main() function. Application classes relate to the Xholon runtime framework by extending the abstract Application class. Your new Java file should be located in the src\org\primordion\xholon\tutorials directory (org.primordion.xholon.tutorials src package in Eclipse).

The detailed runtime behavior of your application can be implemented by XhMyHello in the file XhMyHello.java. Click here to see what the result should look like. Detailed behavior classes relate to the Xholon runtime framework by extending the Xholon Java class or one of its subclasses. In this sample application, XhMyHello extends XholonWithPorts. Your new Java file should be located in the src\org\primordion\xholon\tutorials directory (org.primordion.xholon.tutorials src package in Eclipse).

The third file, CeMyHello.java, contains an int enumeration of all classes defined in ClassNames.txt. You can have this file automatically generated by running CreateClassEnum.java found in the src\org\primordion\xholon\util directory (org.primordion.xholon.util src package in Eclipse). Run it using the command line input argument MyHello. The resulting file should like like this:

// DO NOT MODIFY.
// Automatically generated from config/MyHello/InheritanceHierarchy.xml
// Wed Jun 28 15:38:10 EDT 2006
// To regenerate this file, run  java CreateClassEnum  with the parameters:
// MyHello config/MyHello/InheritanceHierarchy.xml src/org/primordion/xholon/tutorials/CeMyHello.java

package org.primordion.xholon.tutorials;

public interface CeMyHello {

    public static final int XholonClassCE = 0;
    public static final int HelloWorldSystemCE = 1;
    public static final int HelloCE = 2;
    public static final int WorldCE = 3;
}

Compile and execute your application. If you're using Eclipse, run AppMyHello as a Java application. If you're using a console window, then do the following:

1. cd to the Xholon directory:
cd $HOME/Xholon/src  (Unix/Linux)
cd \Xholon\src       (Windows DOS)
2. set your classpath (Unix/Linux or Windows DOS):
CLASSPATH=.:$HOME/Xholon/lib/Xholon.jar:$HOME/Xholon/lib/xpp3_minXHOLON-1.1.3.4.O.jar:$HOME/Xholon/src
set CLASSPATH=.;\Xholon\lib\Xholon.jar;\Xholon\lib\xpp3_minXHOLON-1.1.3.4.O.jar;\Xholon\src
3. compile CeMyHello.java XhMyHello.java AppMyHello.java (Unix/Linux or Windows DOS):
javac -classpath $CLASSPATH org/primordion/xholon/tutorials/AppMyHello.java
javac -classpath %CLASSPATH% org\primordion\xholon\tutorials\AppMyHello.java
4. execute AppMyHello (Unix/Linux or Windows DOS):
cd ..
java -classpath $CLASSPATH org.primordion.xholon.tutorials.AppMyHello
cd ..
java org.primordion.xholon.tutorials.AppMyHello

The output should look like this:

ModelName : My Hello World
AppM : true
InfoM : false
ErrorM : true
MaxProcessLoops : 10
TimeStepInterval : 10
SizeMessageQueue : 1
InheritanceHierarchyFile : ./config/MyHello/InheritanceHierarchy.xml
CompositeStructureHierarchyFile : ./config/MyHello/CompositeStructureHierarchy.xml
ClassDetailsFile : ./config/MyHello/ClassDetails.xml
InformationFile : ./config/MyHello/Information.xml
JavaClassName : org.primordion.xholon.tutorials.AppMyHello
JavaXhClassName : org.primordion.xholon.tutorials.XhMyHello
MaxPorts : 1
Hello World !
Hello World !
Hello World !
Hello World !
Hello World !

Why does the string "Hello World !" print only 5 times, while maxProcessLoops (the number of time steps) is set to 10? This is because each time Hello or World sends an asynchronous message during a given time step, it is only received and processed by its partner during the next time step. This is an event-driven system. All messages sent using the sendMessage() operation are placed in a queue for processing during the next time step. The exchange of messages is shown visually in the following UML sequence diagram. In some of the larger sample applications, multiple Xholon instances send messages during the same time step.

Hello World - Sequence Diagram

Alternatively you can execute the model using the Xholon GUI. Run java -classpath $CLASSPATH org.primordion.xholon.app.Xhn or java org.primordion.xholon.app.Xhn (Unix/Linux or Windows DOS) rather than AppMyHello on the command line. Select File --> Open --> MyHello --> MyHello_xhn.xml. Expand the Controller node, and press Start. The Xholon GUI (based on the Java JTree class) should display the system as shown in the following diagram. As you select different nodes in the Model --> CompositeStructureHierarchy tree, the viewer will display at the bottom of the graphic whatever you have programmed in the toString() function of your behavior class (XhMyHello.java). In the graphic, each Xholon instance has a name consisting of the class name plus a unique numeric id. Hello and World each have a single port that connects to the other active object. After starting the app, the state for Hello will be set to 1, while the World state is 0. Examine the XhMyHello code to see why they have different states.

Xholon GUI

This tutorial has walked you through the creation of a simple system using the Xholon runtime framework. To summarize, here are the steps we followed to model and implement a simple Xholon application:

  1. Decide what xholon classes are needed in the model, and organize them into an inheritance hierarchy.
  2. Model the xholon composite stucture hierarchy.
  3. Model the interaction paths (ports) between xholons.
  4. Create a main configuration file.
  5. Optionally write detailed information about the application, that users can browse at run-time.
  6. Write a Java Application class.
  7. Write a Java class that implements the required xholon activities, organized as a set of simple state machines that pass messages back and forth.
  8. Write or generate a Java class that contains IDs for each xholon class.
  9. Compile and execute the model.
  10. Inspect the executing model using the Xholon GUI.