gEditor, the J-Sim Graphical Editor

Jing Zhang, Ning Li, Dan Clemmensen

Version 0.6, 2004-09-18

This web page Copyright (c) 1998-2004 by DRCL
All Rights Reserved
This work is licensed under a Creative Commons License.

1 Overview

This document is a brief introduction to gEditor. gEditor is a java package that serves as a graphical editor and front end to the J-sim simulation package.
Please note that this version of the documentation is for gEditor version 0.5.

1.1 How gEditor Works

You use gEditor to graphically create and edit a simulation Model. You then use gEditor to run a simulation based on the model. gEditor models can be created, saved, loaded, edited, and run by gEditor.

gEditor uses the J-Sim simulation engine to actually run the simulation. J-Sim simulations are based on Java objects. When you run a simulation, gEditor first creates a Java object instance of the appropriate component class for each component, and updates the internal parameters of each instance to conform to the information you supplied when you created the simulation model. gEditor then passes the root component of your model to J-sim's simulation method, which then runs the actual simulation. If you are not familiar with Java, this may seem strange: the entire configuration for the simulation is passed as a set of active java objects in memory, not as a file. This is easier to understand if you remember that you are actually running only one program: the Java interpreter. In essence, gEditor and J-sim are simply two sets of classes that run as one program through the magic of Java.

gEditor can exersize control over the simulation as it is running. It does this by sending commands to J-sim via J-sim's command console. The command language for these commands is a Java-enabled form of Tcl known as Jacl. This method is used for historical reasons. You will not generally need to issue these commands yourself. Instead, you will click on the appropriate buttons, and gEditor will issue the commands.

Some components create and update output windows as the simulation runs. These windows will appear on your screen when you start the simulation, and will remain on the screen until you terminate the simulation. HINT: depending on your window manager (e.g., MS Windows, Kde, Gnome, etc. ) multiple output windows may obscure each other. Move the topmost output window to see if additional output windows are hidden behind it. Move each of the hidden windows to see if there are additional hidden windows.

gEditor works with all available J-Sim component classes. The component classes available to you will depend on which packages you have installed, and will also include any component classes you may have written. Refer to the J-Sim documentation to learn how to write a new component class. Technically, gEditor can use any class in your CLASSPATH that is a subclass of drcl.comp.Component. Please note that gEditor does not know or care about the nature of your components: if you have a set of components for an IP network simulation, and a different set of components for a highway traffic simulation, gEditor will happily let you mix them all together in one model. (Of course, J-Sim is likely to complain when you attempt to drive a truck into your router.) If you wish to avoid this, you should change your CLASSPATH when you change from one set of component classes to another, prior to invoking gEditor.

gEditor keeps each of your simulations models in a gEditor model file. A gEditor model file is an XML file conforming to the gEditor Model XML schema. While itis possible for you to read and understand a gEditor model file, you should not attempt to edit a model file except via gEditor.

A NOTE ON Tcl/Jacl configurations: When you read the J-Sim documentation, you will find that you can use Jacl commands to create and configure component objects. This was the configuration method used prior to the development of gEditor. Since you are using gEditor, you do not need to do this. Do not get confused. You will also note that gEditor can export Tcl configuration scripts. You do not need to do this, either. The process of emitting a TCL script from gEditor and then running it in J-Sim is very cumbersome and slow by comparison to the default method of passing Java objects. You do need to be aware of this historical use of Tcl to understand the J-Sim documentation and to understand why some of the Tcl features of gEditor exist.

1.2 Installing gEditor

Before you install gEditor, you must first install J-Sim. Refer to the J-Sim documentation.

Note that the following instructions are for version 0.5. Earlier versions have somewhat different instructions.

You will also need some third-party java packages for XML. These are the xalan and crimson packages from Apache and the jaxp package from SUN. Since you may already have them, they are no longer included in the gEditor package. They are available in an add-on package from the DRCL site, but you should probably install them from the originating sites. I recommend that you simply attempt to install gEditor. If this fails, install xalan and try again. Only if this fails, grab the packages from DRCL. In any event, ensure that your Java system can find the packages. This will just happen if the packages are installed in one of the usual places on your system, or you may need to adjust your CLASSPATH.

gEditor is a separate package from J-Sim and should be installed in a separate directory. For example, if you have installed J-sim in ~/j-sim, you might install gEditor in ~/j-sim-gui-x.y. First, make sure that CLASSPATH and all J-Sim's environment variables have been correctly set as described here. Then, download and unpack the J-sim-gui package, and follow the instructions in the README.txt file:

    tar xzvf j-sim-gui-x.y.tar.gz
    cd j-sim-gui-x.y
    more README.txt

On Linux if you have root privileges you will probably want to install gEditor in a directory that everybody can use, such as /usr/share/Jsim-gEditor. If you are installing for yourself only, you should place gEditor in a separate directory in your home directory.

1.3 Running gEditor

Life is simpler if you keep you keep each simulation project in a separate directory, and keep these directories separate from your installation directory. Make a new directory, enter your new directory, and use the following command: gEditor creates a cache file in this directory. It also keeps an icon map file if you change any icon mappings.

java gEditor [<filename.xml>]

2 Description of the GUI

This section describes all of the graphical elements of gEditor. Some of the details require that you understand the J-Sim package. gEditor allows you to create, edit, and execute models . A model is embodied in an XML file that conforms to the XML document standard used by gEditor.

For the purposes of the examples in this overview, create a new directory and put a copy of the file ex3.xml into it. Navigate to your directory and issue the following command:

java gEditor ex3.xml

This will invoke gEditor and load a sample model named ex3.xml that is provided with the package documentation. Now click on the colorful icon in the left-hand white pane, and click on the "key" icon next to it. The result should look similar to this:

As seen in the example, the gEditor main window contains two graphical panes: tree structure and component view. It also contains a menu bar and a tool bar at the top, and a simulation control bar at the bottom. gEditor also makes use of the console window, which is the terminal from which it was launched.

2.1 Tree Structure

The left pane is the Tree Structure, which presents a hierarchical view of the document. All of the components in the document are in this hierarchy. You can show or hide any level of the hierarchy by clicking on the key-shaped show/hide icon next to a component. Each component is represented by the icon of the component's class and the name of the component instance. Click on a component icon or name to cause its internal component view to be displayed in the component view.

By convention, the entire model is a "component." There can be only one model component, and it is the only sub-component of the root of the hierarchy.

2.2 Component View

The right pane is the Component View, which presents a graphical view of the internal structure of the currently selected component in the tree view. This is the area in which you edit the internals of a component. Editing is performed graphically, using techniques similar to those used in other object-oriented graphical editors.

There are minor differences between this editor and other graphical editors. There is also one major difference: since components are hierarchical, a change in the internals of a component can affect the way the component interacts with other components in its parent.

2.3 Toolbar Action Buttons

The first part of the Toolbar provides the following functions (from left to right): New, Open, Save, Up, Undo, Redo, Configuration, About. Five of these (New, Open, Save, Configuration, and About) are simply shortcuts for the equivalent menu items. The remaining three are:

Up: change the component view to the parent of the current component view
Undo: reverse the effects of the most recent edit. Multiple Undos are possible, back to the last time the document was opened.
Redo: reverse the effect of an Undo. Multiple Redos are possible until all Undos are reversed.

2.4 Tool Bar State Buttons

The rest of the Toolbar indicates five different editing states for the component view. The state determines the action that will occur when you perform a mouse click within the component view. Only one state is active at a time. Click on a state button to change to that state. The button is changed visually to indicate the state.

2.4.1 Arrow State

in Arrow state, you can move components and connections by clicking and dragging with the left mouse button. A double click with the left mouse button on a component allows the user to examine the structure of a component by loading the component into the component view.

A click of the right mouse button on a component causes a menu to pop-up. Several options are available there:

Debug displays debug information about the component in the console window.
Rename brings up a dialog which allows you to change the name of the component.
Peek Port attaches a J-Sim listener dialog to the target port (if the target is a component, the listener will be attached to its .info port). Then all the packets send by this port will be displayed in the dialog. Note: packets received will not be shown. (Refer to the J-Sim documentation for further informatin on J-Sim listners.)
Properties brings up the properties popup for the child component, as shown below.

gEditor does not implement a copy command. Instead, it implements a feature known as the template. The template allows you to generate multiple components with the same structure. To use this feature, first right click a component and choose Set as template. You can then right click any other component and choose Implement template. Now the target component has the same internal structure as the template component. Note: Since the target component's structure has changed, it might no longer have the ports it had before. All the connections connected to those ports will be deleted. There is at most one template at any time.

The Properties Popup allows you to modify characteristics of the current component via the property editor dialog:

To change the value of a property, click on its value field. This will bring up a popup. Click on the value field and type in your desired value. If you are happy with the result, click on the "OK" button in this small popup. Otherwise, click on the "Cancel" button in the small popup.

After you have changed all the property values that you wish to change, click on the "OK" button the the big properties popup. If you decide to leave all the properties unchanged, click on the "Cancel" button.

Each type of component has a different set of properties. Refer to the J-Sim documentation for component types supplied with J-Sim. gEditor just passes this information to the component without performing any validity checks.

properties popup

2.4.2 Add State

In the add state, you can add child components into the component view. When you click the left mouse button inside the component view at the location where you wish to add a new component, a dialog will appear. All the available component classes are shown in a tree view. Select a class by left-clicking a class in this view, type a component name into the component name field, and then click the OK button. A new component will appear in the component view.

The list of available component classes is built from the available Java class libraries when the editor is started. If you add a component class to a library, the class will not become visible to the Add command until you restart gEditor or issue the Refresh Library command in the tools menu.

add component popup

2.4.3 Delete State

The delete state allows you to delete components, ports, and connections in the component view by clicking on the object to be deleted. The object can be a component, a port, or a connection.

2.4.4 Add Port State

This state allows you to add a port. When you click the left mouse button, an add port dialog popup will appear. You must provide an ID for the port, and you may provide a group name.

gEditor does not enforce port naming conventions, but underlying J-Sim components typically attach meaning to these names. A port is often described in J-Sim and in gEditor in the form
<ID>@<GroupID>
For example, if the ID is "19" and the Group ID is "up" the port is often known as "19@up" as seen below. If there is no Group ID, the port is shown in the form
<ID>@
For example, if the ID is ".info" and the port has no group ID, it is shown as ".info@"

Add port popup

2.4.5 Connect State

This state allows you to connect two components/ports. When you select this state, two additional items appear on the toolbar: A pull-down menu for the line type, and a color selector. You can choose the type of the connection (straight line or curve) and the color of the connection.In connect state, click two components/ports to connect them together. After two clicks, a connection popup will will appear to let user choose the ports to be connected.

connect popup

This technique is not intuitive and it differs from the connection paradigm used in other editors, but it works. There is no feedback after you select the first component. Do not worry about this. Simply click on the first component, and then click on the second component. Order is important for one-way links: you must select the source first, and then the destination.

The connection popup has a "connection type" pull-down, two panes, and two buttons. To make a connection, first use the pull-down to select either "To" or "And" as the connection type. a "To" connection is a one-way connection from the source to the destination. An "And" connection is a two-way connection. There is a pane for each of the two components. The name of the component is above the pane. The source component is on the left. Each pane contains the available ports within the component. Select a port in each pane, and then click the "Ok" button at the bottom of the popup. The popup will disappear, and a line or curve will now connect the two components.

There is really no such thing as a two-way connection. When you complete an "And" connection, gEditor simply created two separate one-way connections between the same two ports in opposite directions. The two lines are initially drawn together, but you can move them independently (in arrow mode) and delete them independently (in delete mode.)

When you bring up the popup by clicking the source and clicking the destination, either or both may be a port in the component view. In this case, the relevant source or destination pane actually refers to current component, rather than referring specifically to the particular port you clicked on originally. You will need to select the correct port in the pane, even though it seems like you selected it already.

connection port select popup

2.5 Simulation Bar

Use the simulation bar to start, pause, or stop the simulation. The simulation time and the actual running time will be shown. The results of the simulation will depend on the configuration you have created. In general, you will specify outputs that will appear as graphs in pop-ups as the simulation runs.

2.6 Menus

The gEditor window has a menu bar at the top. This menu bar lets you bring up the windows described here.

File Menu: contains the traditional buttons to create, open, and save the document being edited.

New: A new document is generated. All the current components are deleted. There is a shortcut for this function on the task bar.

Open: Open a given .xml file. There is a shortcut for this function on the task bar.

Save: Save the current document. There is a shortcut for this function on the task bar.

Save as: Save the current document to an .xml file.

Exit: Exit the editor.

Simulation Menu: This menu allows you to configure certain non-topological information that is needed as part of the J-sim simulation.

Setup Routes and Setup Timing bring up the popups discussed below.

Build J-Sim Nodes: Choose this item to build J-Sim nodes as component objects without actually starting a simulation. After this, you can choose Console from Tools menu to manipulate the J-Sim nodes using Tcl/Jacl. You will generally not need to do this. This is an advanced feature that can be useful for debugging.

Simulation Start: Choose this item to build J-Sim nodes from the current document and start simulation. Even though Tcl is not used to build the nodes, the simulation command itself is still Tcl. If the document has not been modified since the last time the J-Sim nodes were built, the simulation will be started without rebuilding them. An equivalent way to start simulation is to press in the Simulation Bar.

Simulation menu

Setup Routes: Use this dialog to set up necessary routes for the simulation.	Setup Timing: Use this dialog to set up timing specifications of all components in the simulation.

The From and To fields in the Setup Routes popup, and the Name field in the Setup Timing popup, all refer to components by hierarchical name. The hierarchical name of component is the name, preceded by a slash. preceded by the hierarchical name of the component's parent. The root has no parent and its name is null. In practical terms, the hierarchical name starts with a slash, and then the first name in the tree view and so on down to the node you want, as you can see from the examples above. PLEASE NOTE: These fields will NOT be updated automatically if you change the names of components. The Add button creates a new empty row. The Delete button deletes the currently selected row. You can change any field in any row. After you change a field, click the Update button to make your changes effective.

TCL menu: the GUI editor can also emit the nodes in the older Tcl format. This menu is used to control that process. You will not generally use this feature unless you are adding scripts to an existing suite of TCL scripts.

Tcl menu

Extra TCL: You may need to setup some features at the beginning of a Tcl simulation run, e.g., environment flag, etc. Place the appropriate Tcl commands in this popup. gEditor will insert these commands into the emitted Tcl script when you issue a Tcl simulation start.

PLEASE NOTE: This information is IGNORED when you start a simulation in the standard manner via the simulation menu or via the simulation taskbar. It is used ONLY when you issue a Tcl Simulation start.

Extra TCL popup

Save to TCL Scripts: Convert the current document to .tcl format, which can be loaded to J-Sim console at a later time. Note: some information (including the position of the component) will be lost when save as .tcl format. Also you can not open a .tcl script using graphical editor.

Tcl simulation start: Choose this item will generate tcl code from the current document and start the simulation.

Tools Menu:

Refresh Library: Update the list of available component classes. Because generating the class list is time-consuming, gEditor puts the list in a temporary file when it starts. When new component classes are added to the J-Sim library, we need to choose this item to make the new classes available. You do not need to do this unless you write and install new Java component classes while gEditor is running.

Configuration: You can customize the icon for each J-Sim component class. There is a shortcut for this function on the task bar Choose this item to bring up a dialog to configure the mapping between classes and icons under %GUI_PATH%/images/icon/ directory. If you have customized any icon, gEditor will create a local copy of the icon map and save it in your directory.
If you are an administrator, You can add any icon you want in that directory. Icons can be in either .gif or .jpg format.

Console: Bring up J-Sim console. You can manipulate the simulation using Tcl script. We still use TCL to control the simulation even though the configuration is emitted as Java.

tool menu

Help Menu:

About: Information about the editor.

3 Examples

3.1 Two Hosts, One router and One TCP Connection

Working through this example will take some time. A detailed, step-by-step tutorial is not yet available.

The following is from version 0.04 of this document. As a new user, you should be able to accomplish steps 1 and 2 easily, but step three is an 8-hour job unless you know exactly what you are doing. You should consider running two instances of gEditor, one with ex2.xml open and one with your new file (e.g., mytest.xml.) You will probably be able to create all of the components, ports, and connections correctly, and you can probably create "route" and "timing" by looking in the correct popups in the example. However, this simulation also requires that you set certain properties, and this is non-intuitive, to say the least. You cannot perform a meaningful file comparison on the model files, for various good reasons. V0.5 of gEditor emits the XML in a canonical order, which reduced the differenced somewhat. but there will still be diffreenced in graphical positions. You should ignore these, and analyze the diffferences in the parameters. After all the parameters are correct, running your new file will result in the same simulation results as the original ex2.

NOTE: the properties popup has no way to distinguish a defaulted value from the same value supplied by the user. This can be an important distinction in a few cases. If you wish to revert to using the default value, you must edit your XML file to remove the appropriate <property> tag.

You will create an actual simple network, equivalent to the second example in the J-Sim Inet Tutorial.

Create a node named "ex2" with class "drcl.comp.Component". Note: Only one node under Root is allowed for each simulation. Better give it a name to describe the model.
Create three nodes inside ex2 with name "h0", "n1" and "h2" with class "drcl.inet.Node". Create two nodes with name "l0" and "l1" with class "drcl.inet.Link".
Create the inside structure according to J-Sim Inet Tutorial, including src, tcp, csl. Since many components are similar, using template will save a lot of time.
Create the plotter component with class "drcl.comp.tool.Plotter"
Connect the components together.
Add additional tcl code for simulation
Choose Simulation->Simulation start to run simulation.

Here are the original tcl code, xml code and GUI-generated tcl code. A screen dump of simulation result can be found here.

3.2 TCP Bottleneck example.

Example 3 in inet tutorial is also available. It is a simple 3-TCP-Connections and one-bottleneck example. Here is the xml file. This is the file we used to generate the graphics in section 2.

4 Download & Contact

gEditor can be downloaded from DRCL . As of this writing, the most recent version is 0.6.

gEditor was developed by Jing Zhang and Ning Li. Any comments, suggestions, or bug reports please send to j-sim@cs.uiuc.edu.

Dan Clemmensen made substantial changes to this document, starting with V0.5. You can contact him with suggestions about the document. Comments and suggestions from first-time users are especially useful.

You might want to look at Dan's Wish list for gEditor.

A historical note on terminology: J-Sim was originally named "Javasim," but the name was changed to avoid conflicts with the JAVA trademark policy. gEditor was therefore originally called the "Javasim Graphical Editor" and was then called the "J-Sim Graphical editor." Some vestiges of these former names remain in the code and documentation. I have chosen to avoid this entire problem by using the name "gEditor" throughout this document. "gEditor" is actually the name of the main executable program, not the name of the package.

* JAVA and all JAVA-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

~ END ~