# JAMM User's Guide

This section covers using JAMM.

rJAMM must be installed before use (see rJAMM Installation).

## Contents

#### Starting the Notepad Example

#### Participant Information

#### JAMM Collaboration Controls

#### Initial View Before Sharing

#### Load a File

#### Share Notepad

#### Joining a Shared Component

#### Input Control

#### Sharing An Arbitrary Swing Component

### Starting a Sample Shareable Application - Notepad

The `rJAMM<version>/bin` (<version> is the rJAMM version number. e.g., 0.6.1) directory contains scripts (batch files) for running rJAMM. The two Swing demonstration applications, Notepad and Stylepad, can be run with the `run_Notepad` and `run_Stylepad` scripts (batch files), respectively.

To run the Notepad example, from the rJAMM<version>/bin directory, execute `run_Notepad`. Similarly for Stylepad, execute `run_Stylepad.` Since Notepad uses fewer resources and starts more quickly than Stylepad, you should start with it. Note to MS DOS users: if the application seems to take too long to start up, try starting up your TCP/IP networking (e.g., via Dial-up Networking) and then restart JAMM.

#### Participant Information

Figure 1a. Participant Information. The first time you run rJAMM, you will need to enter some information unique to yourself: your name and a color. These will be used to identify you during collaboration.

#### JAMM Collaboration Controls

The primary JAMM controls are contained in the window named rJAMM Collaboration Controls, as seen in Figure 1b. Figure 1b. JAMM Collaboration Controls window. The upper portion contains two buttons. The Share Component button (disabled in this view), initiates sharing of the component. The Change My Information button allows the participant to change his or her name and color. The lower portion of the window, labeled Input Control allows participants to coordinate input control to the shared application (see Input Control for more information).

After you enter your participant information, your screen should look like this.

#### Initial View Before Sharing

Figure 2. The initial view of Notepad after executing run_Notepad.

#### Load a File

So that we have something interesting to share, open a file by clicking the open-folder icon (second from left) in Notepad. If you are using rJAMM version 0.5.1, do not use the menus yet, because of a known serialization problem with Swing menus. After all participants have joined, you can use the menus safely. The menu problem is fixed in rJAMM version 0.6.1 Clicking the open-folder icon will open a file dialog. Select the file named `hamlet_actI_sceneI.txt` . Your screen should look like the following:

Figure 3. Notepad with the file `hamlet_actI_sceneI.txt` loaded.

#### Share Notepad

Now we can share Notepad. Press the "Share Component" button on the Collaboration Control window. A dialog will ask for a host, port, and session name. Accept the default values by pressing the "Connect" button. If you are using Java versions 1.1 - 1.1.4 you will see a harmless NullPointerException; please ignore this fixed known bug in the Java AWT (fixed in 1.1.5).

At this point rJAMM will make a copy of the objects contained by Notepad. A progress bar will display how much time is left until the copy is sent. On the receiving end, a corresponding progress bar will display how much time is left until the copy is fully received. At the end of this process, your screen should look like the following:

Figure 4. Notepad being shared.

At this point, the Notepad component may be joined by other participants (See Joining a Shared Component). After joining and experimenting with shared Notepad, try `rJAMM<version>/bin/run_Stylepad` to share the Stylepad. Notice the radar view window on the right. See rJAMM Screenshots for an explanation of radar views and why they are important for flexible collaboration.

### Joining a Shared Component

Execute the script (batch file) `rJAMM<version>/bin/joinJAMM` to join a previously shared component (such as the Notepad example above). You may join the shared component from the same or a different machine than it was started on. A "Connection Information" dialog will ask for host, port and session name. Enter the host on which the original shared component is hosted (the default is the local host). If the component was assigned a different session name than the default ("rJAMM"), enter that session name in the 'Session name' field. Press "Connect." Upon connection, the original application will send a copy to the joining participant. A progress bar will display how much time is left before the join is complete.

If you join from the same host machine as the shared component, rJAMM will use the same participant information as you entered previously. After the second rJAMM has joined, you may change the color or name of either to keep the copies distinct.

Figure 5. A participant has joined the shared Notepad. This participant has also scrolled the text up and is viewing a different portion than the original.

### Input Control

To avoid conflicts, collaboration-transparency systems allow only one participant at a time to generate input (mouse and key input). Control is implicitly granted to the first participant to press a mouse button. That participant holds control until he or she releases the mouse button. Control may also be taken by pressing the "Take Control" button in the Input Control panel of the Collaboration Controls window. If the participant who currently has control has not checked the "Keep Control" check-box, control passes to the requesting participant. The new control holder is displayed in the Input Control panel.

Figure 6. The Collaboration Control window contains the Input Control panel.

JAMM relaxes the input control constraint in one case. Multiple users may simultaneously enter text in a text area. See Multiuser Interface Components: Concurrent Editing for more information. Figure 7 illustrates two users simultaneously editing text in a shared Swing Notepad

Figure 7. Two users simultaneously entering text. User A is editing text in the replica on the left and User B is editing the replica on the right.

### Sharing An Arbitrary Swing Component

Any 100% Swing component may be shared via rJAMM. `rJAMM<version>/bin/run_jammviewer` is the script to share components other than Notepad and Stylepad. `run_jammviewer` takes one parameter, the class name of the component you wish to share. The class must have a no-parameter constructor in order for rJAMM to instantiate it. The syntax is:

`run_jammviewer <fullClassName>`

There are two ways to allow JAMM to find the Java class of the component you wish to share.

1. Class files in a JAR File - If your classes are in a jar file, put the jar file in the `rJAMM<version>/jars` directory. For examples of components in jar files, see Other Shareable Components.
2. Class files in CLASSPATH - Simply set your CLASSPATH environment variable to include the path to your class files.

   A simple example, called ButtonTest, is included in JAMM 0.7+ under `rJAMM<version>/classes/test/ButtonTest/`. ButtonTest is a simple Swing component that contains two buttons, "Button A" and "Button B," which disable each other when pressed, as seen in Figure 8 (see ButtonTest.java for sample source code). To share ButtonTest with JAMM, set your CLASSPATH environment variable to `CLASSPATH=rJAMM<version>/classes/test/ButtonTest` (this must be done by the initiator and all joiners of the shared session). To initiate sharing, execute the following command
   `run_jammviewer componentName=ButtonTest`.

   Figure 8. One collaborator's view of a simple Swing component, ButtonTest, shared via JAMM.

Top Level JAMM
JAMM Home