4.0 The GUI

There are two ways to negotiate in and manage context space: command-line utilities such as legion_ls and legion_rm (discussed in See Working in context space ) and with the Legion graphic user interface (GUI). This section discusses the GUI (version 0.1 alpha). The alpha release has a number of limitations, but it is a useful tool for seeing and controlling your context space.

Legion context space is represented in the GUI as a collection of Legion names. These names identify objects that are defined in your Legion system (classes, executables, basic files, contexts, etc.) and are organized into Context Folders (see See GUI Context Folders ). If a Legion name refers to a context (such as /hosts , /class , or /users ), it will appear as a Context Folder (the /class name is highlighted in See GUI Context Folders ). However, all of the elements in a Context Folder can be generically referred to as context members, or more simply as members .

When you first start the GUI you will see a structured view of context space. This view is called a tree view (see See GUI tree view, folders only ). This view is organized as an outline, with each entry representing part of Legion context space. Since contexts generally contain members, the Context Folder will display these members as Legion names in the next outline level below the parent Context Folder.

The outline structure of the tree view can be seen in See GUI Context Folders : the / root context holds file objects and contexts (which can in turn contain other contexts). It also shows that each member of the view identifies the type of Legion object it represents. Context Folders, for example, have a folder icon to distinguish them.

Because this icon is always displayed, you may want to suppress the Context Folder label. (The suppressed preference is fixed in this version, but will be under user control via the Edit Preferences command in a future release.) See GUI tree view, folders only shows a view that is folders only.

You may notice in this example that /Bill and /StatelessClasses do not show folder icons, even though they in fact refer to contexts: See GUI Context Folders shows them with the proper icon. The GUI's cache may not always match the current state of your context space (see See Context space vs. the GUI cache ), so while the GUI knows that /StatelessClasses is a context, it also knows that it does not have the data for that folder available in its cache.

A tree view can produce spawns. A spawn is a new tree view based on the member selected in the current tree view. As described below, a spawned view window can be added to the windows on your screen, or replace the window that spawned it. A variety of parameters allow you to specify what is displayed by a new view window.

4.1 Installing the GUI in Windows 95

You must have the Java Runtime Environment (JRE) or the Java Developer Kit (JDK) 1.1.3 or later in order to run this application. You can download these from <http://java.sun.com/products>.

The files for running the GUI in Windows95 must be stored in a specific directory configuration. The installation package is in the LegionGui.zip file. It consists of three parts: binaries, libraries and classes. Move the package to your hard drive, then unzip it.

The unzipped package must have the directory structure shown below. If you are using WinZip be sure to check the Use folder names option before extracting the files. All directory names must appear as shown, particularly the GUI classes, since these names reflect the package structure of the program.


The \Bin subdirectory holds the jre.exe, and the *.dll files. The \Lib subdirectory holds the *.jar files and classes.zip. The remaining directories hold the compiled classes of the GUI program.

The GuiStart.bat file is in the \LegionGui directory, but you can move it anywhere in your current machine's directory structure. It assumes that the directory structure above is in c:\, but you can put the unzipped package in any part of your current machine. If the GUI files are not on the c:\ drive you must alter the GuiStart.bat file accordingly.

4.2 Running the GUI in Windows95

There are two steps to this process:

  1. 1. Open a Telnet or Exceed window to your Legion host, and execute the following command:
$ javaLegionServer 
      1. This will return a port number <PPP> .
      2. 2. Open a DOS window. Move to the directory containing the \LegionGui directory structure (e.g., c:\), and type the following into the Run dialog:
GuiStart <my_host> <PPP>
      1. The <my_host> argument is the address of the Legion host computer (e.g., host.cs.virginia.edu). The <PPP> argument is the port number produced by the JavaLegionServer command in step 1. This will load the GUI and display its initial view of your context space.
4.3 Running the GUI in a Unix environment

Please see the Legion web site for information about installing and running the GUI in a Unix environment.

4.4 The main GUI window

All views appear within the GUI main window. This window takes up the full screen and has a main menu bar immediately under the window title. The menu shows the full complement of commands contemplated for the Legion GUI.

The complete set of GUI commands fall into three main categories: manipulating Legion classes, objects and data; navigating and manipulating context space; and managing the GUI itself. Most of these commands are dimmed to indicate that they are not yet available for use in the current release. The available commands allow you to add, replace, and control view windows.

In order to display Legion context space information on the screen, the GUI creates a highly structured memory cache in your computer. The GUI gets the data for this cache from the Legion host computer via a port you specify when you start the GUI. Legion context space can be quite large, so when the GUI first starts up the initial tree view window shows the GUI context space / root context and only three levels of context folders. (This is an Edit | Preferences limitation and is fixed in this version.) From here you can tailor one or more view windows with the View | Add and View | Replace commands. You can also directly modify this startup view with the View | Extend command.

The GUI's initial display of context space may therefore be smaller than the actual Legion context space. You can use the View | Add , View | Replace and View | Extend main menu commands to extend the number of levels appearing in any view window.

In order to close all currently open view windows and exit the GUI, click the File | Exit command on the main menu bar.

4.5 View windows

From the main window you can open multiple view windows, which show selected parts of your context space. Every view window has a view origin, or origin. This will always be a Context Folder and is the zero level of its tree view.

The first view window displayed on startup uses the context space root as its view origin. This is designated by the symbol / and is an absolute point of reference in the GUI. It represents the highest level of the data contained in the GUI cache.

The more general term root can be used to indicate a view origin that is other than / ; i.e., a context member at a different point in the tree. Figure 2 shows a tree view with view origin / . A selected context, such as /home , can be used as the view origin for the creation of a new tree. Any context in any view can be used to create a new view window with that member as its view origin.

The title bar of each view identifies its view origin and the number of levels in that view. The context path of any member relative to the view origin is easily determined from the path shown in the title bar.

To close a view window, click the closure icon at on the right side of the title bar. This will remove the view from the screen entirely. It cannot be recovered. There is no command in this version to generate a view without a spawn, so once you have closed the last view window you must restart the GUI to open a new view window.

4.6 The startup view window

The initial view window is currently fixed in this version, but in future versions you will be able to select the initial portion of context space shown. The startup view window is a folders-only tree view showing up to three levels of folders from your context space. This view can be extended with the View | Extend command or used to spawn additional view windows with the View | Add command. The spawned view windows can in turn spawn other views or be replaced with the View | Replace command.

4.7 Main menu commands
4.7.1 File

File | Exit

This command closes all view windows and exits the GUI.

4.7.2 View

View | Extend

The Extend command lets you extend the current view window down one level.

If the selected member is a folder the command extends only the members of that folder. This allows you to focus on a particular branch of the context space tree

If the selected member is not a folder the entire view is extended down one more level. This means that every empty folder is checked for children and those children are displayed.

View | Add

The Add command lets you add a new tree view to your screen. In the current version a sub menu is displayed with only the Tree selection available. This selection opens a dialog box labelled New View Specification ( See GUI New View Specification window ).

The New View Specification dialog box has three areas of interest. These are Display , Origin At and Levels .

Display: You can select Folders Only to create a view that shows only folders and no non-folder members (as in See GUI tree view, folders only ). Select Root to display the view origin. Select Root Level to display the children of the view origin, and not the origin itself. The Root and Root Level buttons act like radio buttons (i.e., they are mutually exclusive). The Folders Only button is independent of the other two.

Origin At: The Root button creates a new view window with a view origin that is the same as that of the spawning view window. The Selection button creates a new view with the current selection taken as its view origin. The Context Space Root button sets / as the origin of the new view window. These three buttons are mutually exclusive.

Levels: This section specifies how many levels of context space should be displayed in the new view window.

If you wish to alter the tree in the new view window relative to your current (spawning) view, select Yes in the View Relative? option. You can indicate that you want to extend, reduce or leave unchanged the number of levels to appear in the new view relative to the spawning view. You should then either enter a number in the Number Of Levels field or choose one of the buttons offering fixed settings (e.g., if you want to reduce the number of levels by one you would select Reducing and then enter 1 in the Number of Levels field).

If you select No for View Relative? you can specify an exact number of levels. In this case, the Extending and Reducing buttons are dimmed, and the 1 Level Only button is removed (a view window tree displays a minimum of two levels).

In either case you can use the Number of Levels field to set the number of levels. The current release limits this value to five new levels in a single View | Add operation. Selecting the Maximum Of 5 Levels button is the equivalent of entering a value of 5 in the Number Of Levels field.

The default setting is a relative view, extended by one level.

View | Replace :

The Replace command lets you replace the current view with a new tree. In this version, a sub menu is displayed with only the Tree selection available. This selection displays a dialog box labelled Replacement View Specification . It is the same dialog box shown in See GUI New View Specification window .

Replacement View Specification : All buttons in this dialog box operate the same as described above for View | Add .

Extend: The created view is extended by the Number of Levels entry. Extension occurs at the lowest level of the view.

Reduce: The created view is reduced by the Number of Levels entry. The reduction occurs at the lowest level of the view.

Unchanged: The new view is created with no change in the number of levels.

View | Clone :

This command creates an exact copy of the spawning view window and adds it to those already on the screen.

View | Close :

You can close the current view window with this command. No other view will be affected and no other view window will be selected. You will have to select a new view window before you can execute any further menu commands.

You can also close any view window on your screen with the view closure button on the right side of the title bar.

4.8 Context space vs. the GUI cache

The GUI gets information for its cache from your Legion system. This information is brought in from Legion one level at a time, as required by the cache. This cache requirement is driven, via the commands on the main menu, by the actions you take.

Since it would adversely affect performance if Legion simply dumped all data it has available about context space in the GUI's cache, the GUI limits the amount of information called for by any one command. In the current version, this limit is set at three levels for the initial view window and a maximum of five levels in any subsequent view windows.

The flip side of this is that the context space information available in the GUI cache at any given moment may be incomplete. As a consequence, the GUI may not know whether or not leaf folders at the lowest level of your context space have members until you specifically call for information about them. The display will carry the legend (Context) as part of their labels but the folder icon will not appear in the display. This indicates that Legion has not been queried below that level of cached information.