Tutorial:
Legion 1.3 graphical user interface (GUI)


Table of Contents

  The Legion GUI
Starting the Context Manager
Starting the GUI on Windows95
Shutting down the GUI
Restarting the GUI
Using the GUI
The GUI Icons

Other relevant on-line documents:
  Starting and shutting down Legion 1.3
Logging in to a Legion system
Legion context space
Legion host and vault objects
How to start remote programs in Legion
Quick list of all Legion commands
Usage of all Legion commands

The Legion tutorials offer quick and simple instructions for various key procedures for a Legion system. More complete explanations of all of the procedures discussed here are available on separate pages, and can be found by clicking on the icon.

Depending on how your system is set up, you may need to set up your access to your system before you can run Legion commands. This will probably involve running a command such as this:

$ . ~LEGION/setup.sh

or

$ source ~LEGION/setup.csh
The exact syntax will depend on what kind of shell you are using and on where your Legion files are installed. Consult your system administrator for more information.


The Legion GUI

The Legion graphical user interface (GUI) is a Java application that allows users to run context-related commands in a graphical interface. The Legion GUI uses icons to represent different parts of context space (file objects, sub-contexts, etc.). Pull-down menus and mouse-driven processes make it easier to navigate and use this space, although some processes will still need to be started from the command-line.

The GUI can be run from a command line or Windows95. The Context Manager can be run from the command line of any platform compatible with the Java Development Kit (JDK) 1.1.3. A Windows95 client application, called the Legion Server, allows users to run the Context Manager from Windows95.


Starting the Context Manager

You must have a Legion session already running when you run the Context Manager. Before compiling the Context Manager be sure that your machine has JDK.1.1.3 or later.

  1. Add the following to your CLASSPATH environment variable.
    $LEGION/src/Java/client/:$LEGION/src/UserInterface/swing.jar:.
  2. Add the JDK bin directory to your path (i.e., /home/jdk1.1.3/bin).

  3. To compile the application and the necessary classes, go to the $LEGION/src/UserInterface directory and enter:
    $ make
  4. Export the CLASSPATH variable and set your DISPLAY variable, if you have not already done so. Start the application with the legion_java command. This process will only run in the $LEGION/src/UserInterface directory.
    $ legion_java ContextMgr &

Starting the GUI on Windows95

The Context Manager must be compiled on the machine running your Legion session before the Legion Server, the Windows95 client application, can be started. You also need to have either the Java Runtime Environment (JRE) version 1.1.3 (or later) or JDK version 1.1.3 (or later) installed on your Windows95 machine. You can obtain either from http://java.sun.com/products/.

Note that you will actually be running two separate applications, one on the command line of the machine running your Legion session and one on a DOS window on your Windows95 machine.

  1. Install JRE or JDK on your Windows95 machine if you have not already done so. Add the bin directory for either package to your path in the AUTOEXEC.BAT file (e.g, PATH=C:\jre\bin).

  2. On the machine running your Legion session, go to the $LEGION/src/UserInterface directory and copy the file called Legion.zip (it was created when you compiled the Context Manager) to your Windows95 machine. Unzip the copy.

  3. Start a Java Legion Server: run the javaLegionServer command on the machine running your Legion session. The process will return its machine's name and a port number:
    $ javaLegionServer &
    javaLegionServer: a.machine.name 1234
    $

  4. Start the client on your Windows95 machine: open a DOS window and go to the $LEGION/UserInterface directory. Type in:
    $ Legion [machine name] [port#]
    Use the machine name and port from the output of step three (i.e., a.machine.name 1234).

The Legion Java client will open in a separate window, titled the Legion Context Manager, and can be manipulated like a normal Windows95 windows. You can continue to work on machine running your Legion session, since the Java client is running in the background. Note that closing the DOS window will also close the Legion Context Manager window.


Shutting down the GUI

To shut down the Legion Context Manager or the Legion Server simply close the appropriate window.


Restarting the GUI

To restart the Context Manager from the command-line repeat step 4 above.

To restart the Legion Server repeat steps 3 and 4 above.


Using the Legion GUI

The GUI can be used in place of context-related commands to manage context space: all context-related objects such as contexts, file object, and objects are represented by icons and can be manipulated with the mouse.

Note that changes to context space made from the command line are not automatically updated in the GUI. Users should refresh their current context as necessary. Changes made in the GUI, however, are reflected in the context space and can be viewed with command utilities (i.e., legion_ls or legion_context_list).

Click the right mouse button in the main GUI window to open a box with three options:

Create Context   Create a new sub-context in the current context
Import File   Import a copy of a local file into Legion space. A separate window will appear, with the option to browse through local file space and specify a filter to use when copying the file into Legion space.
Import Directory   Import a local directory into Legion space or from Legion space into local disk space. A separate window, showing the local file system, will appear.

The pull-down menus can be used to do the following:

File-> New-> Open New Window
   Open a new Context Manager window. This will point to the same context space as the original Context Manager window.
New File
Create a new File Object. A New File window will open, where you can enter the new object's context path name, then a text editor window will open. The Ctrl-n key combination will also run this process.
New Context
Create a new sub-context in the current context
    View File
   Display contents of a selected textual file object in a separate window.
Import File
Import a copy of a local file into Legion space. A separate window will appear, with the option to browse through local file space and specify a filter to use when copying the file into Legion space. The Ctrl-i key combination will also run this process.
Import Directory
Import a local directory into Legion space or from Legion space into local disk space. A separate window, showing the local file system, will appear.
Export File
Export a copy of a local file to local disk space. The Ctrl-e key combination will also run this process.
Quit
Close the current window. If only one window is open, the program will exit. The Ctrl-x key combination will also run this process.
Edit-> File-> View File
   Opens a Text Editor window, where you can edit the file's contents.
Copy File
Make a copy of the file object. This will create a new object, with a new LOID and context name but with the same content. The Ctrl-c key combination will also run this process.
Export File
Export a copy of a local file to local disk space. The Ctrl-e key combination will also run this process.
Class->Run...
Executes a previously registered executable program class. Click here for information about registering remote programs and here for information about running remote programs in the GUI. This option will produce a separate window, which can be used to specify input and output file names. The Ctrl-p key combination will also run this process.
Show Instances
Display all instances of a selected class in a separate window. This option returns several pieces of information about the selected class's instances, as shown below.


It lists each instance's LOID, status, Object Address (OA: an active object's location), Host, and Vault. The Instance pull-down menu allows users to activate, deactivate, and destroy selected or all instances, as well as to refresh the window. The Ctrl-p key combination will also run this process.

Activate All Instances
Activate all instances of a selected class. The Ctrl-a key combination will also run this process.
Deactivate All Instances
Deactivate all instances of a selected class. The Ctrl-d key combination will also run this process.
    Move
   Change the object's context name and remove the old name from context space. This will not affect any other context names that have been assigned to the object by you or any other user.
Alias
   Assign another context name to the selected object. Clicking this option brings up a new window to enter in the new name. Note that you can specify a different context path, if you wish to place the name in a different context. Another object icon, with the new context name but referring to the same LOID, will appear in the appropriate context.
Get Interface
   View the selected context object's interface.This information will appear in a separate window. The Ctrl-g key combination will also run this process.
Get Attributes
   View the selected context object's attributes. This information will appear in a separate window. The Ctrl-h key combination will also run this process.
Destroy
   Destroy a selected object's path name and/or the object itself. A "Destroy" window will appear, where you should specify whether you want to destroy just the object's context name or the object (both its context name and its LOID). The Ctrl-Delete key combination will also run this process.
Activate
   Activate a selected, currently inert, object.
Deactivate
   Deactivate a selected, currently active, object, i.e. move it to an inert state.

The GUI icons

There are five icons in the GUI, each representing a part of context space. Each icon is labeled with its context name: objects without a context name will not appear in the GUI. Clicking the right or left mouse button on the icons will allow you to carry out various actions, explained below.

The context icon represents a context, similar to a Unix directory. You can change your current context by double-clicking on a context icon. Click the right mouse button to get the following options:

  Move
Alias
Get Interface
Get Attributes
Destroy
Activate
Deactivate

The parent context icon represents the current context's parent context. Double-clicking this icon will moe you back to the parent context.

The class icon represents a class object. You can double-click a class icon to see a list of the class's instances. Click the right mouse button to get the following options:

  Show Instances
Run...
Move
Alias
Get Interface
Get Attributes
Destroy
Activate
Deactivate

The instance icon represents an instance of a class object. Click the right mouse button to get the following options:

  Move
Alias
Get Interface
Get Attributes
Destroy
Activate
Deactivate

The file object icon represents a file object. Double-clicking this icon opens a text window displaying the file's contents. Click the right mouse button to get the following options:

  View File
Copy
Export File
Move
Alias
Get Interface
Get Attributes
Destroy
Activate
Deactivate

In all contexts, users can refresh the current context by clicking on the upper left hand "." context icon (left). Similarly, users can always get to a sub-context's parent context by double-clicking on the ".." parent context icon, to the right of the "." context icon (right). Note that the parent context icon will not appear if you are currently in your home context.