Legion 1.4
Basic User Manual


3.0 Graphical user interface

The easiest way to become get acquainted with Legion is to become familiar with Legion context space. Context space is a way of organizing Legion objects and can be thought of as a network-wide transparent file system. It is similar to Unix's system of directories and files but while Unix space is location specific, context space can potentially include objects anywhere in Legion. In this space you assign string names, here called context names, to Legion objects. Context names have no relation to an object's physical location or type but are designed to help you to find, use, and track your objects.

You maintain your own context space, organizing it to reflect your needs. There are two ways to negotiate and manage context space: from the command-line, using command-line utilities such as legion_ls and legion_rm, and with a Legion graphic user interface (GUI) called the Context Manager.

3.1 About the GUI

The Legion GUI is a Java application that runs context-related commands in a graphic interface called the Context Manager. The Context Manager uses icons to represent different parts of context space (file objects, sub-contexts, etc.) and allows you run most context-related tools.

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.

3.2 Running the Context Manager from the command-line

Before compiling and running the Context Manager be sure that your machine has JDK.1.1.3 or later installed. Note that you cannot start the ContextMgr process from outside the $LEGION/src/UserInterface directory.

  1. Add the following to your CLASSPATH environment variable:
  2. $LEGION/src/Java/client/:$LEGION/src/UserInterface/swingall.jar:.
  3. Add the JDK bin directory to your path (i.e., /home/jdk1.1.3/bin).
  4. To compile the application and the necessary classes, go to the $LEGION/src/UserInterface directory and enter:
  5. $ make
  6. You must have a Legion session already running. Be sure to export the CLASSPATH variable, set your DISPLAY variable, and stay in the $LEGION/src/UserInterface directory. Use the following command to start the application:
  7. $ legion_java ContextMgr &

    A new window will pop up in your Unix window (see Figure 1). If you get errors at this point, check that your environment is properly set and that your DISPLAY variable is correct.

    The Context Manager does not have to be run in the background, but otherwise your command line will be inactive: some utilities can only be run from the command line, so we suggest that you keep the command line active.

Figure 1: Command-line Command Manager

3.3 Running the Context Manager on Windows95

In order to run Context Manager on Windows95 you'll need to follow steps 1-3 outlined in Running the Context Manager from the command-line on a machine running your Legion session and to start Legion Server, a Windows95 client application. The make command, run in step 3 above, creates a file called Legion.zip in your $LEGION/src/UserInterface path. The zip file contains the classes needed to run the Server.

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 download these from <http://java.sun.com/products/>.

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

  1. Follow the JRE or JDK installation instructions for Windows95 if they are not already installed. You must add the bin directory for either package to your path in the AUTOEXEC.BAT file (e.g, PATH=C:\jre\bin).
  2. Copy the file Legion.zip to a directory in your Windows95 machine and unzip it (be sure that your unzip program maintains extended filenames).This will create a new directory called UserInterface in your Windows95 directory. The new directory contains the appropriate classes for running the client.
  3. On the machine running your Legion session start a Java Legion Server by running javaLegionServer. This process will output the name of the machine it is running on and a port number to your command line.
  4. $ javaLegionServer &
    $ javaLegionServer: your.machine.DNS.name 25568

    We recommend that you run javaLegionServer in the background, although again it is not necessary.

  5. To start the client on your Windows95 machine, open a DOS window, change the path to the UserInterface directory created in step 2, and type the following:
  6. $ Legion your.machine.DNS.name <port>

    Use the machine name and port given in the output from step 3. The Legion Java client will open in a separate window, titled the Legion Context Manager, and can be manipulated like a normal Windows95 window. The window will look something like Figure 2.

    Figure 2: Windows95 Context Manager window

    You can continue to work on the machine running your Legion session if the Java client is running in the background. Closing the DOS window will also close the Legion Context Manager window.

3.4 Shutting down the Context Manager

To shut down the Legion Context Manager, simply close the Context Manager window or enter Ctrl-X.

3.5 Restarting the Context Manager

To restart the command-line Context Manager, repeat step 4 from Running the Context Manager from the command-line. To restart the Windows95 Context Manager, repeat steps 3 and 4 described in Running the Context Manager on Windows95. You will get a different port number each time you run the Context Manager.

3.6 Using the Context Manager

The Context Manager can be used in place of context-related commands to manage context space: context space is organized into a series of sub-contexts (also called contexts) and each context contains context names of various Legion objects, similar to Unix space's directories and file names. In the Context Manager all context-related objects such as contexts, file objects, and objects are represented by icons that can be manipulated with the right and left mouse buttons.

Click the right mouse button in the Context Manager window to reveal three basic options: Create Context, Import File, and Import Directory.

Create Context
Create a new sub-context (similar to a Unix sub-directory) in the current context. A new window will appear to ask you to name the new context. The new sub-context will be placed in your current context, unless you specify via a full context path name (e.g., you can place the new sub-context in the parent context by using ".." in the new context's full path name).

Import File
Import a copy of a local file into Legion space. That is, copy the local file's contents into a new Legion file object. A separate window (Figure 3) will appear. If you click on the "Browse" button you can browse through your local file space. Be sure to give the new object a context name.

Figure 3: Importing a file in the Context Manager

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. You can type the directory path in the Current Directory cell or browse through your local system by clicking directory names in the Subdirectories cell.

3.6.1 The Context Manager icons

There are six different icons in the Context Manager, each representing an element of context space. The context name associated with the object will appear beneath the icon. Objects that do not have a context name will not be represented in the Context Manager, so not all objects will appear: with the exception of the default names created when your system was started you create your own context names. You can use the Context Manager to create, change, and remove context names by clicking the right or left mouse button on icons. The icons are explained in full below.

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

Move
Change the object's context name and delete the old name from context space. This does not actually move the object, but changes its name. Note that an object can have multiple context names, assigned by you or by any other Legion user. Move 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. The new name will be placed in the current context unless you use a full context path. Another object icon, with the new context name but referring to the same object, will appear in the appropriate context.

Get Interface
View the selected object's interface. The information will appear in a separate window.

Get Attributes
View the selected object's attributes. The information will appear in a separate window.

Figure 4: Destroying contexts in the Context Manager
Destroy
Destroy a selected context name and possibly its associated object. A new window will appear (Figure 4) offering two options: if you choose Remove Path, the context name will be destroyed but the object will remain, but if you choose Remove Path and Object both the name and the object will be destroyed.

Activate
Activate the selected object.

Deactivate
Deactivate the selected object.

The "go-up" icon represents the current context's parent context. Double-click the left mouse button on this icon to change your current context to the parent context. Clicking the right mouse button will produce the same options as with the context icon (above).

The class icon represents a class object. You can double-click the left mouse button on a class icon to see a list of the class's instances (Figure 5). This opens a new window that 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.

Figure 5: Context Manager list of class instances

Click the right mouse button to get the following options:

Show Instances
Display all instances of a selected class in a separate window. This opens the same window shown in Figure 5.

Run...
Executes a previously registered executable program class. Please see Executing remote programs for information about registering remote programs, and Running a remote program from the GUI for information about running remote programs in the Context Manager. 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.

Move
Change the object's context name and remove the old name from context space. This carries out the same function as the Context icon Move option (see Move).

Alias
Assign another context name to the selected object. This carries out the same function as the Context icon Alias option (see Alias).

Get Interface
View the selected context object's interface. The information will appear in a separate window.

Get Attributes
View the selected context object's attributes. The information will appear in a separate window.

Destroy
Destroy a selected context name and possibly its associated object. This carries out the same function as the Context icon Destroy option (see Destroy).

Activate
Activate the selected class object.

Deactivate
Deactivate the selected class object.

The runnable icon represents a class that has been registered for execution with Legion. Double click this icon to see a list of the class's instances. Click the right mouse button to show a drop down menu and its Run command, or select Edit, Class, Run to initiate the execution. Prior to starting execution a window will pop-up to allow you to specify input and output files and any command-line parameters.

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

Move
Change the instance's context name and remove the old name from context space. This carries out the same function as the Context icon Move option (see Move).

Alias
Assign another context name to the selected instance. This carries out the same function as the Context icon Alias option (see Alias).

Get Interface
View the selected context object's interface.The information will appear in a separate window.

Get Attributes
View the selected context object's attributes. The information will appear in a separate window.

Destroy
Destroy a selected context name and possibly its associated instance. This carries out the same function as the Context icon Destroy option (see Destroy).

Activate
Activate the selected instance.

Deactivate
Deactivate the selected instance.

The file object icon represents a file object. Double-click the left mouse button on this icon to open a text editor window displaying the file's contents. The text editor allows users to edit file objects. Click the right mouse button to get the following options:

View File
Display contents of selected file object in a separate window.

Copy
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.

Export File
Export a copy of a local file to local disk space.

Move
Change the instance's context name and remove the old name from context space. This carries out the same function as the Context icon Move option (see Move).

Alias
Assign another context name to the selected instance. This carries out the same function as the Context icon Alias option (see Alias).

Get Interface
View the selected context object's interface. This information will appear in a separate window.

Get Attributes
View the selected context object's attributes. This information will appear in a separate window.

Destroy
Destroy a selected context name and possibly its associated instance. This carries out the same function as the Context icon Destroy option (see Destroy).

Activate
Activate the selected instance.

Deactivate
Deactivate the selected instance.

You can refresh your current context by clicking on the current context icon (Figure 6). Similarly, users can always get to a sub-context's parent context by double-clicking on the "go-up" icon. Note that the "go-up" icon will not appear if you are currently in your root context.

Figure 6: Refreshing the Context Manager
Click on the current context icon to refresh the Context Manager's current icon

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

3.6.2 The Context Manager pull-down menus

The pull-down menus (Figure 7) 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.

Figure 7: Context Manager menus
  
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. This carries out the same function as the Create Context option in the Context Manager.

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.

Figure 8: Context Manager menus
  

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.


Figure 9: Context Manager menus
  

Class-> Run...
Executes a previously registered executable program class. Please see Executing remote programs for information about registering remote programs, and Running a remote program from the GUI 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. The Show Instances option returns several pieces of information about the selected class's instances, as shown in Figure 5.

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 carries out the same function as the Context icon Move option (see Move).

Alias
Assign another context name to the selected object. This carries out the same function as the Context icon Alias option (see Alias)

Get Interface
View the selected 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 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 context name and possibly also the object itself. This carries out the same function as the Context icon Destroy option (see Destroy). 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.


Back to Basic User Manual Table of Contents