Tutorial:
Legion 1.3 graphical user interface (GUI)

Table of Contents

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

---