The Model Explorer Tool

Model Explorer is a visual tool to perform and visualize composition of an AHEAD model and its instances. This document explains how to use the model explorer and to compose features of models.

 Starting the Model Explorer

To run ModelExplorer, type:

> ModelExplorer 
or 
> java ModelExplorer.Main

ModelExplorer is packaged as a JAR file and should be in your CLASSPATH.

The Model Explorer’s window comes up (Figure 1). Since no argument was given to specify the model directory, the current directory is used. The window is split in halves: The left side is used for browsing and provides three methods for selecting units (as indicated by the tabs on top): A tree view of model (tab Tree) or a relational view that can be queried as explained in section 4 (tab Query) or a matrix navigator which can navigate the model as hierarchal matrix (tab Navigator). The editor in the right side displays a selected unit in two different modes: one can view the content of a unit, or one can edit it (tab Editor). On the right side, there are three other panels: the equation editor (tab Equation), the composer panel (tab Composer) which is an interface to run the composer tool to build a new project, and the output panel, which is a watch window to show running results.

                        Figure 1: Model Explorer Starts up and shows the model

When closing the ModelExplorer, the state of the ModelExplorer tool will be storied into a properties file named _MEState.properties  So when opening the ModelExplorer , only if this property file exists, it will get its state from this file and restore it. Currently, the state includes: last opened model, active equation and its composition dir, a list of file extensions (matrix filter).

 Opening a New Model and Resetting the Model

Opening a new model
After the model explorer starts, the user can open any model from the menu Model.Open or by clicking open icon  on the toolbar. The file chooser dialog will pop up. It allows the user to browse directories and choose the model directory to open. Only Directories are shown in the dialog. Figure 2 shows the model directory GEN is opened. 

When opening a model, if there is a property file named _Filter.properties in the model directory, all the files and directories specified in that property file will be ignored. If there is no such property file in the model directory, the default file in the tool will be used, which ignores only the file .cvsignore and the directory CVS in the model. That means, the ModelExplorer uses the user specified file together with the default one to generate a global filter to remove unwanted files from the view. An example of such a properties file is given shortly.

                             Figure 2a:  Opening the GEN model directory

                                  Figure 2b: The GEN model was opened
 

There is a list of MRU models in the "Model" menu. By default, it provides at most four most recent models' links to allow user to open them quickly. Using the menu Options->Perferences->Others, users can change the number of the most recent models.

             Figure 2c: The "MRU" list in the "Model" menu

Figure 2d shows the format of a file _Filter.properties is. This file is a global filter to apply to all the three types of browsing in the model explorer: tree browsing, query browsing and matrix navigator.

                                   Figure 2d: The default file _Filter.properties in the Model Explorer tool.

Basically, the prefix property name "filterfiles" represents the properties which specify the unwanted files. The prefix property name "filterdirs" represents the properties which specify the unwanted directories. The values in the properties are separated by space. The number after the prefix property name should start from 1 and then to 2 and so on, without skipping. That means, if filterfilter2 is not defined, then there are no filterfilter3, filterfilter4 ... properties defined in the file.   This "feature" allows filter definitions to be spread across multiple lines.

Resetting the model

The user can use the menu Model.Reset or the short cut Reset icon  on the toolbar to refresh the displayed model at any time. Any changes in the model directory, like newly added files, will become visible. For example, if we add a new directory jtsdocs inside the GEN model, then after clicking the reset icon, the jtsdocs will be displayed (Figure 3).

                            Figure 3: Resetting the GEN model , the newly added layer (directory) is displayed

 Tree Browsing

The Tree displays the model in its natural format, as a hierarchy. A first glance shows us that all the subdirectories of the model directory are there, as layers. Exploring layer Benchmark confirms that the Java and Layer files in its directory have been turned into units, as well. If we click Benchmark/Graph.jak, the unit pane on the right displays its code (extended java code) in a syntax-highlighted style (Figure 4). The content of fopdocs/ASTConstructors.html is shown as rendered HTML (Figure 5). Right now, ModelExplorer can display .Java, .Layer, .Jak, .html, .xml source code in syntax-highlighted style. It also can display the HTML file and .gif and .jpg files (Figure 6).

The source code can be modified using EDIT pane under the "write mode" of the editor. The detail of the editor is in the section Source Code Editor.

                 Figure 4: The Graph.jak is displayed in the viewer by clicking Benchmark/Graph.jak on the tree view

                            Figure 5: The ASTConstructors.html is selected and displayed in the unit pane

                             Figure 6: The Backward.gif is selected and displayed in the unit pane
 

 Query Browsing

Apart from the obvious presentation as a tree, ModelExplorer also displays a model as a database relation. Browsing a model then means to query the relation in a database language. The following rules turn the model tree into a relation:

  • The relation holds all units of the model with the exception of the root unit. The key of a tuple is the path (excluding root) to the unit as an array of roles. When we display a tuple, we omit the unit field.
  • If a model tree has n levels, the maximum length of a path is n-1. A key that is shorter than n-1 contains null roles to fill the empty columns. Null roles are displayed as <->. If the unit is primitive, null roles are inserted before the last role in its path. Null roles in the paths of collectives are inserted at the end.
  • The roles in the i-th column are all from level i of the unit tree (the level of root is 0). Accordingly, the title of that column is “Level i”. (We also call the last column “Artifact”).


The Query tab in the top left corner provides us with more sophisticated means for browsing: The model tree is displayed as a relation and can be queried through a column of select lists ( Figure 7). At first, the whole model is displayed in the query result table. Notice that the unit that was last selected under the Tree tab is selected here, too. The selections of the two tabs are always synchronized. The equivalent of the tree gadget is only the right half of the tab, the query result; the select lists narrow the results, but are not used for activating units. Therefore, specifying a query has no effect on what unit is currently displayed.

    Figure 7:  The Query tab shows the model as a relation that can be queried. The parameters of the query are given
    in the select lists.

By selecting the row in the result table, the artifact will be displayed in the unit pane (if it’s a displayable artifact). The rows in the result table can be sorted according to a specified column by clicking the column header (Figure 8).

Figure 8: The rows in the result table are sorted according the column layer by clicking the layer column header.    The selected Vertex.jak is displayed in the unit pane

Now, we perform two queries to show how the query browsing works. First, we want to find out what’s in layer Connected. Listing the content of Layer Connected is achieved by the SQL statement:

        select * from Rel where Layer="Connected"  (where "Rel" represents the name of example relation in the fig 7 & 8)

This query can be sent to the ModelExplorer by clicking on the Connected item in the list Layer. The query results change and display an answer to our question (Figure 9 left).

Before we execute the second query, we clear our selections by clicking the Deselect all button. (We also could click on the title of the list Layer, which deselects just this one list). The second query is that we want to find out what layers Edge.java is part of. The following statement retrieves all the layers that contain a artifact Edge.java:

      select * from Rel where Artifact="Edge.java"

This query can be sent to the ModelExplorer by clicking on artifact Edge.java in the list Artifact which shows us what layers Edge.java is part of. (Figure 9 right).

           Figure 9: Example queries.  Left:   What are the contents of  layer Connected? (Connected, *, * ).
                                                    Right: What layer is Edge.java a part of? (*, *, Edge.java).

Generally, for visual browsing, we want to get rid of SQL and represent a query as a tuple.

(where  is the title of column j ,  is any of the values in that column and )
Any query can be converted to a tuple  as follows. The projection function  returns the set of values of column j of relation s.

The tuples for example queries (1) and (2) are (Connected, *,*) and (*,*, Edge.java). The graphical user interface for specifying t is a set of n - 1 select lists  that display  . That way, select list  presents all possible values for component  of the query tuple.

 Matrix Navigator

The matrix navigator allows a programmer to navigate the model in two dimensions:

First, it allows to navigate the containment hierarchy of collectives.  This is a one-dimensional navigation – up and down collective hierarchies. Second, it allows to navigate across inheritance hierarchies. This is a second dimension navigation – up and down the inheritance chain. That mean, in a navigation matrix, it not only shows the list of data members, methods, etc. of the current class/ interface/ and state machine.  If this class/etc. extends another class, then it will show the set of methods, members, etc. that this class inherits.

To make this more concrete, we open a new model “fsats”. When the “Navigator” tab is clicked, the matrix navigator is loaded.  The combo box in the toolbar allows the user to choose the equation file. The matrix navigator is created according to the specified equation file. By default, the navigator will include all the layers in the model. (The query browser will be reloaded according to the specified equation file simultaneously.)         

                       

                                   Figure 10. Loading the navigator matrix

 

           

                      Figure 11a. The navigator matrix was loaded

During loading the navigator matrix, each artifact is parsed by the mmatrix tool in the JTS to get its “Artifact type” and other information. In the navigator matrix, the first column is “Artifact Type”, the second column is “Artifact”. The other columns are the layers. (The first layer column “.” represents the root directory of the model.) The letters in the matrix represent:

  • Compound Artifact:


            "C"                  Class
            "I"                   Interface
            "S"                  StateMachine or State
            "+"                  SubDirectory

  • Primitive Artifact:


            "T"                  Transition
            "K"                  Constructor
            "M"                 Method
            "F"                  Field

  • Refined States:


            "D"                 Defines      - Artifact is defined in this file.
            "E"                  Extends     - Artifact (class, interface, state methods) extends a previous defined artifact.
            "R"                  Refines     - Artifact is refined in this file.

If the cell is empty, that means the artifact in the corresponding row doesn’t exist as a layer in the corresponding column.
If the cell if filled by "1", that means the artifact exists in the corresponding layer but the detailed type is unknown.

By using "Options->Preferences...->Matrix Filter", users can specify a list of file extensions for which to apply mmatrix. ("jak" is the only default value). If the list is changed, the "apply" button will be enabled. Clicking "apply" or "ok" button, the matrix navigator will be reloaded according to the new specified matrix filter.

       Figure 11b: The "Matrix Filter" panel to specify a list of file extensions

Basically, there are at least four level navigators to switch. Their order is:

Followings are the common events for the navigator:

Event01: Clicking the column header, the navigator matrix is sorted according to the value in that column. (When the navigator is loaded, it is sorted by the “Artifact” column.)

        Figure 12. The  “BasicL” header was clicked, so the rows in the matrix were sorted by the values in that column.
        Here, the empty cell has biggest value so all empty cells in that column are in the bottom of the matrix

Event02: By left clicking the cells in the layer’s columns, the corresponding artifact is shown in the viewer pane.

               Figure 13. When left clicking the cell, the corresponding row and column are highlighted in a different color,
               and the corresponding artifact is shown in the viewer pane

Event03: By right clicking the cells in the layer’s columns, a popup menu appears which contains all the super classes/interfaces/state-machines/etc of this artifact as its items. By clicking each item in the popup menu, it will navigate you to the corresponding super classes/etc. if that super class exists in this model.

                                        Figure 14. The popup menu.

           

           

            Figure 15. After clicking the menu item “Target” in the above popup menu, the artifact “Tartet.jak” row is
            selected and shown up.

Event04: Clicking each cell in the “Artifact” column, the composition artifact file is shown in the viewer pane only if there is a specified equation file for that navigator. If not, a dialog will be popped up to remind you. Or if the composition directory isn’t in the current model directory, a dialog will be popped up to allow you to give the composition directory the first time.

                       

          Figure 16. When clicking the cell “BnFseMission.jak” in the artifact column, one dialog is popped up since there’s no
          active equation.

           

                   Figure 17: Reloading the navigator by choosing one equation file in the combo box on the toolbar

 

                       

             Figure 18: After reloading the navigator, click the artifact “FlightTime” again, one dialog popped up to
             allow you give the composition directory since the composition directory is not in the current model directory

           

           Figure 19: After give the composition directory, the corresponding composite file is shown on the viewer pane

Event05: Clicking each cell in the “Artifact Type” column expands to the corresponding containment hierarchy navigator matrix (named second level navigator). There are two cases in this event:

CASE1: The corresponding artifact is a subdirectory, not a file. (represented by "+").  In this case,  by clicking this "+",
    the matrix navigator expands to another matrix which represents the corresponding subdirectory. If there are
    more subdirectories in the subdirectory, the matrix navigator can be expanded further, until no more subdirectories.

Figure 20a The subdirectories show up in the matrix after sorting the matrix by "Artifact Type". Note that this
    subdirectory was copied into the layers "ProxyL" and "OpfacL" just for demonstrating this case. (Currently there is no
    actual model which has subdirectories in its layers).

                   

               Figure 20b Click the "+", The subdirectory matrix shows up and the up button in the toolbar becomes enabled.

    CASE2: The corresponding artifact is a file. In this case,  the matrix extends to the jak matrix.

    Figure 20c: clicking the artifact “MissionImpl”, the second level navigator pops up.  In the second level navigator,
    there is a “Super” column next to “Artifact” column, which represents the corresponding methods/fields/etc. coming
    from the hierarchical chain.

Event06: By left clicking the cells in the layer’s columns, the artifact that includes the corresponding method/field/etc is shown in the viewer pane with the corresponding method/field/etc highlighted.

                           Figure 21: The method “canElevate() Boolean” was highlighted in the viewer pane.

Event07: The “Forward” and “Back” arrows in the toolbar allow you to switch between the different level navigators. The "Up" arrow in the toolbar allows you back to the upper lever matrix from the subdirectory matrix.

        Figure 22: Clicking “back” button in the Figure 20, The navigator was switched to the model navigator from the
        jak navigator.

Event08: The “Error check” button in the toolbar provides function to check the current navigator according to the order of the artifact in the different layers. If there are errors in the current navigator, the errors list will be given in the “tools” panel. Clicking each item in the error list will navigate you to the error artifact in the navigator matrix. Currently, the idea of error check is to make sure that artifacts is not defined before they are refined. So in one row of the navigator, "R"s can't appear before any of "D"s or "E"s. This is a useful "feature" to validate a composition prior to composing it.

               Figure 23: By clicking “Error Checking” icon on the toolbar, the current navigator is checked. The result
               is given in the tool panel if there is no error in the current navigator.

           

               Figure 24: If there are errors in the current directory, the errors list is shown in the output window.

           

               Figure 25: By clicking on the item on the errors list, the corresponding artifact in the navigator is selected.

Event09: The “Reducing size” button in the toolbar provides function to use the regular expression to specify the row or column pattern and therefore reduce the first level navigator matrix to view.

    Figure 26: By clicking the “Reducing size” icon in the toolbar, a dialog pops up and allow you to input the regular
    expressions for the rows and columns. “.*” means any possible string. “.*L” means any possible string which ends with
    “L”. The expression for rows specifies the pattern for artifacts. the expression for columns specifies the pattern for
    layers. Only the artifact that matches the above two patterns is shown in the matrix.

           

               Figure 27: The result navigator only shows the layers in the model whose name ends with “L”.

For semantics of regular expression, refer to Regular Expressions in Java Tutorial.
 

 Source Code Editor

The source code is shown in the viewer/editor pane. By using "Options->Read Only" or the icon in the toolbar, user can switch between the two modes: read only or editable. There are several functions for editting.

  • General file operations: new, open, close, save, save as, print. These functions can be accessed by the menu "File" in the menubar. Some of them also can be accessed by using the icons in the toolbar.
  • General editting operations:
      • cut, copy paste
      • undo, redo
      • find, find again, replace

           

                                          Figure 28:  The editor pane.

 Equation Editor

Equation editor is a pane that allows you to edit the equation files easily. Actually, the equation editor is a Jlist.

           

                            Figure 29: The equation editor.

The operations are available in the equation editor:

  • By clicking the “Existing Equations” button in the equation editor pane, the equation file list in the combo box will be updated to show all the existing equation files in the current model directory.

               Figure30: The existing equation files was updated into the combo box by clicking the left button “Existing Equation”.

  • By choosing one of the equation files in the drop down list, the corresponding equation file will be opened in the equation editor.

                               Figure 31: The “FS.equation” file was opened.
 

  • Using “Del” button can delete the items selected in the equation editor.
  • Using “Del All” button can delete all the items in the opened equation file.
  • Using “New” button can create a new equation file.

Figure 32: After clicking the “New” button, a new empty equation file is ready to be edited.

  • Clicking the item in the tree view, the corresponding layer or artifact will be added into the equation editor in order.

               Figure 33: First click the item “AddRmiL” and then “ArtilleryL” in the tree view, these two items were added into
               the equation editor in the order of clicking.

  • Inserting. First select the item in the equation editor after which you want to insert the new item, then click the item you want to insert in the tree view, the new item will be inserted after the selected item in the equation editor. After inserting, the selected item in the editor will be the new inserted item.

 For example, we want to insert the layer “BasicL” after “AddRmiL”:

           

                               Figure 34: First select the item “AddRmil” in the editor.

           

               Figure 35: Then click the item “BasicL” in the tree view, the “BasicL” will be inserted into the editor after the
               item “AddRmiL”.

  • At last, the editing equation file can be saved by using “Save” or “SaveAs” button.

 Tools panel

The tools panel is an interface to allow the user to run the tools in AHEAD suite. By integrating the ant1.6.5, ModelExplorer generates an ant project object from a given ant script file. This ant project object provides all targets which can be invoked at run time. Each target corresponds to each tool in AHEAD suite that we want to invoke by the tools panel. Each target name (also the corresponding tool name) is put on the tools panel as a button. The parameters of each tools are parsed out from the ant target and put in the options panel.  Currently, the tools available in the tools panel are: composer, jak2java, java2calss, reform, unmixin and checker.

 

           

                                  Figure 36: The tools panel.

 

           

                                  Figure 37: The tool options panel for each tool

Add or remove tools from the tools panel

Since the ant project gets all targets by parsing the specified ant script file, ModelExplorer.xml, it’s easy to add or remove tools from the tools panel by simply add or remove the targets in the script file ModelExplorer.xml. We don’t need to change any code of ModelExplorer. Following is a segment of text for composer tool in ModelExplorer.xml:

<target

        name="composer"

        depends="use.jts.lib"

      description="Composes the layers specified in equation file.">

 

      <property name="composer.jar"   location="${jts.lib}/composer.jar"/>

      <property name="unit.file.jak"  value="MixinFileUnit"/>

      <property name="unit.file.jak@more" value="JamPackFileUnit"/>

      <property name="logging"        value="warning"/>

      <property name="logging@more"   value="all;fine;info;severe;off"/>

 

      <delete dir="${layer}" />

 

        <java

            jar="${composer.jar}"

            failonerror="true"

            fork="true"

            taskname="compose">

 

            <jvmarg value="-Dtool.ant="/>

          <jvmarg value="-Dunit.file.jak=${unit.file.jak}"/>

 

          <arg value="--logging=${logging}"/>

          <arg value="--equation=${layer}.equation"/>

        </java>

 

      <antcall target="reform"/>

 

    </target>

To remove the composer tool from the tools panel, we just need to remove this segment of text from the ModelExplorer.xml file and then copy this file into the AHEAD “lib” directory. When you restart the ModelExplorer, the composer tool in the tools panel will disappear.

To add a new tool into the tools panel, say the added bcmixin tool in AHEAD suite, we just need to add a target in the ModelExplorer.xml:

<target

        name="bcmixin"

        depends="use.jts.lib"

      description="A byte code composer, composing the layers specified in equation file.">

 

      <property name="bcmixin.jar"   location="${jts.lib}/bcmixin.jar"/>

 

      <delete dir="${layer}" />

 

        <java

            jar="${bcmixin.jar}"

            failonerror="true"

            fork="true"

            taskname="bcmixin">

 

            <jvmarg value="-Dtool.ant="/>

 

          <arg value="--equation=${layer}.equation"/>

          <arg value=”--modelname=currentmodel”/>

        </java>

 

 </target>

 

After modify the ModelExplorer.xml file to add in the bcmixin target, we need to copy it into AHEAD build/lib directory (suppose you will not rebuild the AHEAD). Then we restart the ModelExplorer, the bcmixin tool shows in the tools panel.

 

              

                      Figure 38:  The new added tool bcmixin appears in the tools panel

 

To run the composer tool, we first need to choose an equation from the drop down list in the equations box. Then we need to change its options in the options panel if needed. You could go into the options panel by clicking the “options…” button in the tools panel. Then you can start the composer driver by clicking the “composer” button.  The running output will show in the “Running Output” text area simultaneously.

           

                   Figure 39: Running the composer to compose a new project.

 GuiDsl panel

GuiDsl panel is an interface to run the GuiDsl application. In the GuiDsl panel, you can specify an existing model file in your computer and give some input options by the checkboxes.

                       

                                              Figure 40: The GuiDsl panel to start the GuiDsl application

                       

                                              Figure 41: Choosing the model file model.m for GPL model

After choosing the model file and giving the options, the graphical user interface of GuiDsl application will show up in another window. 

                       

 

ATS Home Page

Copyright © Software Systems Generator Research Group. All rights reserved.
Revised: April 17, 2003.