Formalisms

Authors: J.Ferber, O. Gutknecht (c) 2001

  1. What is a formalism
    1. Building a simple graphical formalism
    2. Adding behaviors to nodes and arrows
  2. Formalisms files
    1. Header section
    2. Connector types section
    3. Node types section
    4. Arrow types section
    5. Action list section
  3. The sedit-formalism DTD
  4. Installed formalisms
    1. Automaton
    2. Logical gates
    3. Module based {{ou Module tutorial ???}}
    4. Petri
    5. Bric
    6. Tutorial
    7. MicroWorld serie {{???}}
      1. WarBot
      2. Preys

What is a formalism

This documentation is still incomplete (well, it's a beta), but already provides most of the information needed to build a new formalism.

A formalism is a model definition that represent domain-specific nodes and links (i.e. UML models, Petri nets, logical gates, ...). A formalism is basically a list of nodes and links. It is possible to define basic properties for these elements and valid connections.

A SEdit formalism is defined as a XML file using our sedit-formalism.dtd. XML knowledge is not mandatory but reading some basic tutorial material will help (such as the XML FAQ).

Formalism files can be created and edited with any text editor. But it's definitively more convenient to use a XML editor (or something which knows to interpret DTD files). There is an interesting list of tools at . I personally use the Xeena Editor from IBM.

Building a simple graphical formalism

In this section we will see how to define a new simple formalism without any behavior.

Here is the definition of a (very) small formalism, called tutorial1, which contains three node types and two arrow types.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE formalism SYSTEM "sedit-formalism.dtd"> <formalism name="tutorial1" description="a simple tutorial example">
<formalism-info>
<author>Jacques Ferber</author>
<author>Ol. Gutknecht</author>
</formalism-info> <node-types> <node-desc name="round node" class="SEdit.SimpleNode"> <icon url="images/place1.gif"/> </node-desc> <node-desc name="rectangular node" class="SEdit.SimpleNode"> <icon url="images/transition1.gif"/> <graphic-element class="SEdit.Graphics.GRectangle"> <property name="width">80</property> <property name="height">40</property> </graphic-element> </node-desc> <node-desc name="iconic node" class="SEdit.SimpleNode">
<icon url="images/monalisa.gif"/>
<graphic-element class="SEdit.Graphics.GIcon">
<property name="imageaddress">images/monalisa.gif</property>
<property name="width">40</property>
<property name="height">40</property>
<property name="labelLocation">4</property>
</graphic-element>
</node-desc>
</node-types> <arrow-types> <arrow-desc name="link1" class="SEdit.SArrow" description="A link from anything to anything"> <icon url="images/arrowwithsharpedge.gif"/> <graphic-element > <property name="displaylabel">false</property> <property name="endingForm">2</property> </graphic-element> </arrow-desc> <arrow-desc name="link2" class="SEdit.SArrow" from="round node" to="round node" description="A link from node1 to node1"/> </arrow-types> </formalism>
 
	  

Here is an example of its use:

In this example, the general section, after the XML header, contains only some information about the name and description of the formalism, followed by the authors of the formalism.

Its node list section describes three types of nodes:

  1. The first one, called round node is associated to the Java class SEdit.SimpleNode and its icon for the element palette can be found at the location images/place1.gif (an icon which is commonly used for describing places in automaton and Petri nets). And that's all!! All other properties are derived from default properties of SEdit nodes.
  2. In the second the <graphic-element ...> tag add all the necessary information to describe the visual representation of elements in SEdit. Here, we see that this node is represented by the Java class SEdit.Graphics.GRectangle of width 80 and of height = 40 (size numbers are given in pixels).
  3. In the third one, the node is visually represented on the screen by an icon, i.e. by an image stored in a .gif file whose location is given through the imageaddress property. Another property, the labelLocation property describes where the label of the element (i.e. its name) should be placed.

Its arrow list section contains two types of arrows, link1 and link2. Globally the description of arrows is similar to that of nodes. There are two main differences:

  1. In the graphic properties, there are the startingForm and endingForm properties which describes the beginning and ending shapes of arrows. The list of available shapes can be found here.
  2. The <arrow-desc ...> tag contains two optional fields from and to. These fields are used to set some constraints on the source and target node. In our example, the link2 arrow can only connect round node to round node.

Adding behaviors to nodes and arrows

It is quite easy to provide some behavior to nodes and arrows, to simulate an operational model (as for Petri nets or finite state automata for instance), to compute some functions (as for logical gates for instance), etc..

To do so, one has to define classes in Java that derives (directly or indirectly via subclasses) from SNode for nodes and SArrow for arrows. See the following sections for more details.

Formalisms files

In this section, we will provide all the details neccessary to understand and build your own formalism.

A formalism file is made of five section:

  1. The header section
  2. The connector types section
  3. The node types section
  4. The arrow types section
  5. The action list section

1. Header section

The header section, after the general tags of any XML file, contains some global information about the formalism itself. It holds the mandatory name attribute which identifies the formalism, an optional description attribute and an optional class attribute which corresponds to the Java structure class. See {{link}} for more details on Java structures.

Information about the formalism is defined by the <formalism-info> tag. Here are the possible attributes:

Here is the header section of the Tutorial1 formalism.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE formalism SYSTEM "sedit-formalism.dtd"> <formalism name="tutorial1" description="a simple tutorial example">
<formalism-info>
<author>Jacques Ferber</author>
<author>Ol. Gutknecht</author>
</formalism-info>

Here is the header section of the DataFlow formalism {{link}}. This header shows a documentation tag in the formalism-info section.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE formalism SYSTEM "sedit-formalism.dtd"> <formalism name="DataFlow"> <formalism-info> <author>Olivier Gutknecht</author> <doc url="http://www.madkit.org/mydoc.html"/> </formalism-info>

Here the header section of the Automaton formalism. This header shows a class attribute within the formalim tag, which expresses that SEdit should use the structure class SEdit.Formalisms.Automaton.AutomatonStructure instead of the standard SEdit.Structure class.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE formalism SYSTEM "sedit-formalism.dtd">
<formalism name="automaton" description="Automate (et simulation)"
class="SEdit.Formalisms.Automaton.AutomatonStructure">
<formalism-info>
<author>Jacques Ferber</author>
<author>Ol. Gutknecht</author>
</formalism-info>

2. The connector types section

{{to be finished}}

3. The node types section

General

The <node-types> section holds one or many <node-desc> definition. A simplistic <node-desc> tag only contains the name attribute, as for the following node types section which contains only the most simple node description:

  <node-types>
    <node-desc name="Process"/>
  </node-types>

A node description can also store information about the graphic element which can represent the node, configure default properties for both the node and its graphical representation, etc.. If a class attribute is set, SEdit will instantiate a specialized Java class for these nodes. A optional description attribute will allow for the documentation of the node and will appear as a tool tip in the element palette of a diagram editor window:

    <node-desc name="state" class="SEdit.Formalisms.Automaton.AutomatonState"
               description="a state">
</node-desc>

Graphic representation

Many information about visual appearance of may be associated to a node description. An <icon url=..> tag allows for the assocation of an icon to a node type. This icon will be used in the element palette instead of its name to refer to the node type.

A graphic-element tag may be used to describe the graphical representation of a node in the editor. This tag contains a class attribute which describes the Java class which should be used to display the node. By default, SEdit uses the class SEdit.Graphics.GOval. Values may be specified to properties of the graphic element. Standard graphic properties are width, height, labelLocation and displayLabel. The first three properties accepts integers while the latter accepts only boolean. All properties have default values (see the table below).

Here is the definition of a node which is represented as a rectangle of width 80, of height 40, which display its label (i.e. its "name") at

   <node-desc name="rectangular node" class="SEdit.SimpleNode">
<icon url="images/transition1.gif"/>
<graphic-element class="SEdit.Graphics.GRectangle">
<property name="width">80</property>
<property name="height">40</property>
<property name="displayLabel">true</property>
<property name="labelLocation">4</property>
</graphic-element>
</node-desc>

All graphic classes derives from the Java class SEdit.Graphics.GObject which describes the following attributes:

Name Type of value Default value Description
width integer 40 width of the node
height integer 40 height of the node
displayLabel boolean true show/do not show the label of the node
labelLocation integer 5 (CENTER) specifies the location of the node label relative to the node

Here are the possible label locations. The default label location is 5 (Center):

Number Position Description
1
RIGHT the label is displayed on the right of the node
2
LEFT the label is displayed on the left of the node
3
TOP the label is displayed above the node
4
BOTTOM the label is displayed just below the node
5
CENTER the label is displayed in the middle of the node
6
TOP_RIGHT the label is displayed above and slightly on the right of the node

Here is the list of the general graphic representation classes which are provided for nodes.

More Java graphic representation classes will be provided with future releases of SEdit.

Here is an example of a node which is represented as an icon:

    <node-desc name="iconic node" class="SEdit.SimpleNode">
<icon url="images/monalisa.gif"/>
<graphic-element class="SEdit.Graphics.GIcon">
<property name="imageaddress">images/monalisa.gif</property>
<property name="width">40</property>
<property name="height">40</property>
<property name="labelLocation">4</property>
</graphic-element>
</node-desc>

All graphical properties may be modified using the graphical property editor.

Properties on nodes

It is possible to add properties directly to nodes. Two properties are provided as standard: the label property and the comment property. The first one may be used to specify a general label to all nodes of a given type. The second one may be used to add comments to nodes.

It is quite easy to add new properties to node. A property is just a pair of "getter/setter" methods, generally associated to a class attribute, declared as public. For instance, in the Automaton formalism, the modification of the character associated to a transition is defined in this way in the AutomatonTransition class:

public class AutomatonTransition extends SimpleNode 
{ ........ // lot of code here... public char c='#' ; // the character the transition can read /**
* Get the value of c.
* @return Value of c.
*/
public char getTransitionValue() {return c;}

/**
* Set the value of c.
* @param v Value to assign to c.
*/
public void setTransitionValue(char v) { this.c = v; setLabel(""+c); } }

Java actions on nodes

It is possible to add java actions to nodes. These actions will appear in the pop-up menu associated to a node (to learn how to trigger these actions from the editor see SEdit U ser manual/Using the diagram editor/Local actions on nodes and arrows).

To add an action to a node, in the Java class associated to that node, just create a Java method declared as public with no arguments and with return type void. Then add a tag of the form <action description="nom methode"> within the node description of the formalism file. For instance, in the Automaton formalism, the validate method of the AutomatonTransition class is defined in the following way:


public boolean activated=false;
public String currentWord; public void validate() { if (activated){ if (inArrows != null) for(int i = 0; i < inArrows.size(); i++) ((AutomatonLink)inArrows.elementAt(i)).consume(); if (outArrows != null) for(int i = 0; i < outArrows.size(); i++) ((AutomatonLink)outArrows.elementAt(i)).produce(currentWord.substring(1)); } else System.out.println("Error, non active transition!!"); }

In the related formalism file, automaton.xml, the transition node is described as follows:

    <node-desc name="transition" class="SEdit.Formalisms.Automaton.AutomatonTransition">
<icon url="images/transition1.gif"/>
<graphic-element class="SEdit.Graphics.GRectangle">
<property name="width">10</property>
<property name="height">40</property>
</graphic-element>
<action description="validate">
<java-method name="validate"/>
</action>

</node-desc>

4. The arrow types section

The <arrow-types> section holds one or many <arrow-desc> definition. Arrow descriptions are very similar to node descriptions. Here are the differences:

  1. For the moment, there is only one graphic class GArrow which is the graphic class used by default.
  2. There are some new properties associated to the graphic class, relative to the shape of arrows ends.
  3. It is possible to add constraints on the origin and destination of arrows with the to and from attributes (which must be set to already defined node-desc names).

For instance, here is the definition of the arrow types section of the Automaton formalism:

  <arrow-types>
<arrow-desc name="link" class="SEdit.Formalisms.Automaton.AutomatonLink">
<icon url="images/arrowwithsharpedge.gif"/>
<graphic-element>
<property name="displaylabel">false</property>
</graphic-element>
</arrow-desc>
</arrow-types>

We can find the definition of the Java class associated to that node, the icon which is displayed in the element palette, and the displaylabel property which is set to false.

Graphic properties

It is possible to specify the shape of both starting and ending edge of an arrow. Just use the properties startingForm and endingForm, with an integer value corresponding to the following table:

Number Shape Description
0
NOTHING No shape.
1
SHARPEND Classic head arrow style, filled with plain black
2
SQUAREEND The head is drawn as a little square, filled with plain black
3
ROUNDEND The head is drawn as a little circle, filled with plain black
4
DIAMONDEND The head is drawn as a diamond
5
WHITESHARPEND Classic head arrow style, filled with plain white

Default values are the following:

 		<property name="startingForm">0</property>
<property name="endingForm">1</property>

There will be more shapes for arrows in future releases of SEdit.

It is also possible to specify an arrow without any joint (articulation point). To do so, use the property lineStyle with a value of 1. Default value of lineStyle is 0 which correspond to a line with a joint. Here is the definition of a direct arrow without any joint:

 		<property name="lineStyle">1</property>

Constraints

It is possible, from the formalism file, to specify the type of nodes that are accepted as origin or destination of arrows. To to so, just add the attribute to and from to the arrow-desc tag. For instance, to specify that an arrow or type link has as origin a node of type typeNode1 and as destination (or target) a node of type typeNode2, do the following :

 	<arrow-desc name="link"
class="SEdit.SArrow" from="typeNode1" to="typeNode2"/>

The following figure shows an example (see the Tutorial2 formalism) of several types of arrows with different ending shapes, constraints and line style:

5. The action list section

The action list section define the set of global actions that are added to the user toolbar (see SEdit U ser manual/using the diagram editor to get an overview of the use of the editor). Adding a global action is similar to adding an action to a node. The main differences is that the Java method has to be defined in the Structure class of the formalism, and that it is possible to associate an icon, which will be displayed in the user toolbar, to that action.

For instance, in the Automaton formalism, the global action run, which activates the automaton, is declared in the formalism file as follows:

<formalism name="automaton"
class="SEdit.Formalisms.Automaton.AutomatonStructure"> .... <action description="Run">
<icon url="images/run.gif"/>
<java-method name="step"/>
</action>

and here is the definition of the AutomatonStructure which is merely dedicated to the definition of the step Java method.

public class AutomatonStructure extends Structure {

Vector activated=new Vector();
....
    public void step() {
       if ((activated != null) && (activated.size()>0)) {
         AutomatonTransition a = (AutomatonTransition)activated.firstElement();
         a.validate();
         activated.removeElementAt(0);
       } 
    }
}

The sedit-formalism DTD

Here is the definition of the XML DTD of SEdit formalismst. It is possible to use a XML Editor to play with this DTD.

<?xml encoding="US-ASCII"?>
<!-- This SEdit-Formalisms DTD (c) 1999 by MadKit/SEdit Development Team -->

<!-- Element descriptions -->

<!ELEMENT formalism (formalism-info,connector-types?,node-types,arrow-types?,action*)>

<!ELEMENT formalism-info (author+,doc?,icon?)>

<!ELEMENT java-method EMPTY>
<!ELEMENT scheme-function (#PCDATA)>
Not implemented yet
<!ELEMENT action (icon?,(java-method|scheme-function))>
<!ELEMENT property (#PCDATA)>

<!ELEMENT arrow-desc (icon?,graphic-element?,property*,action*)>
<!ELEMENT arrow-types (arrow-desc+)>

<!ELEMENT connector-desc (icon?,graphic-element?,property*)>
<!ELEMENT connector-types (connector-desc+)>

<!ELEMENT connector (property*)>
<!ELEMENT module (connector*,property*)>

<!ELEMENT icon EMPTY>
<!ELEMENT graphic-element (property*)>
<!ELEMENT node-desc (icon?,graphic-element?,module?,property*,action*)>
<!ELEMENT node-types (node-desc+)>

<!ELEMENT doc EMPTY>
<!ELEMENT author (#PCDATA)>

<!-- Attributes -->

<!ATTLIST icon
url CDATA #REQUIRED
>

<!ATTLIST java-method
name NMTOKEN #REQUIRED>
<!ATTLIST scheme-function
name NMTOKEN #REQUIRED>

<!ATTLIST action
name NMTOKEN #IMPLIED
description CDATA #REQUIRED
>

<!ATTLIST property
name NMTOKEN #REQUIRED>

<!ATTLIST arrow-desc
name ID #REQUIRED
description CDATA #IMPLIED
class NMTOKEN #IMPLIED
to IDREF #IMPLIED
from IDREF #IMPLIED
category NMTOKEN #IMPLIED
>

<!ATTLIST node-desc
name ID #REQUIRED
description CDATA #IMPLIED
class NMTOKEN #IMPLIED
category NMTOKEN #IMPLIED
>

<!ATTLIST connector-desc
name ID #REQUIRED
description CDATA #IMPLIED
class NMTOKEN #IMPLIED
mode (In | Out) #REQUIRED
category NMTOKEN #IMPLIED
>

<!ATTLIST module
type (Free | Fixed) #REQUIRED
layout (Auto | Justified | Manual) "Auto"
>

<!ATTLIST connector
type IDREF #REQUIRED
name NMTOKEN #IMPLIED
side (Left | Top | Right | Bottom) #IMPLIED
ratio CDATA #IMPLIED
>

<!ATTLIST graphic-element
class NMTOKEN #IMPLIED
>

<!ATTLIST doc
url CDATA #REQUIRED
>

<!ATTLIST formalism
name ID #REQUIRED
description CDATA #IMPLIED
class NMTOKEN #IMPLIED
>

Installed formalisms

There are many predefined formalisms in SEdit. These formalismes may be used directly as such or serve as basis for the definition of more specialized formalisms.

Here is the list of predefined formalisms: