The Gubdemo Example System

All elements of Gubdemo are in the demo directory. The demo system includes:

gubdemo.jar, containing the class definitions for two Java application programs:
- Gubd, a simple Gubcast server.
- Gubshell, a graphical user interface (GUI) that can be used to command Gubd to push information out to users.
Complete source code for both Gubd and Gubshell.
A set of HTML files that implement a simple Gubcast-enabled Web page.

The Gubdemo programs are designed to be useful not only as a way of getting familiar with the capabilities of Gubcast but also as a basic template for developing your own Gubcast-based system. Gubd may actually be a little more complex than some Gubcast servers, though its code is pretty straightforward: Gubd is a "double-sided" server that supports two different kinds of clients, the Gubshell interface as well as Gubcast applets.

Running the demo system

To run Gubdemo, do the following:

Place the Gubdemo HTML files plus the gubcast.jar jarfile (from the lib directory) in a single directory that is accessible from your Web server. On a Red Hat Linux system with an Apache http server, for example, they might go into a directory named /var/www/html/gubdemo.
Start Gubd running on the same machine as your Web server. Gubd takes no runtime parameters, so to start it you only need to cd into a directory that contains both gubdemo.jar and gubcaster.jar and enter the following command:
```
java -classpath ./gubdemo.jar:./gubcaster.jar Gubd
```
or, on a Windows machine,
```
java -classpath .\gubdemo.jar;.\gubcaster.jar Gubd
```
Gubd is intended to be run indefinitely in background as a "daemon" process, so on a Linux or other Unix host you might want to use this variant of the Gubd start command:
```
java -classpath ./gubdemo.jar:./gubcaster.jar Gubd &
```
Start Gubshell, which will immediately connect to Gubd. Gubshell takes a single runtime parameter: if you run it on a machine other than the one on which Gubd and your HTTP server are running, then you must supply the fully qualified host name of that server machine. (When you omit this parameter, Gubshell attempts to connect to a Gubd running on the local host.) To run Gubshell, cd into the directory that contains gubdemo.jar and enter the following command:
```
java -classpath ./gubdemo.jar Gubshell
```
or, for Windows,
```
java -classpath .\gubdemo.jar Gubshell
```
Or, if Gubd is running on a machine named "glop.com":
```
java -classpath ./gubdemo.jar Gubshell glop.com
```
or, for Windows,
```
java -classpath .\gubdemo.jar Gubshell glop.com
```

From here on, anyone who uses Netscape or Internet Explorer (or any other browser that can load the Java plug-in) can navigate to your Gubdemo by simply entering a URL that maps to your directory of Gubdemo HTML files. In the Linux example above, this would be something like http://yourdomainname/gubdemo.

Whenever this happens, the page that appears in the user's browser window will have three frames: menu, top, and bottom. The "menu" frame contains the Gubcast applet, which will start running shortly after the page is received (provided the Java plug-in is installed on the user's machine and the loading of plug-ins is authorized at the browser). The applet will register with the Gubd server, which in turn will notify Gubshell; the client name "test" will appear in the dynamic "Client:" menu of the GUI.

At this point you can use Gubshell to push content to the "test" client:

Select a target for the content:
- One of the named frames "top" or "bottom", or a new window with a frame name that you select.
- A new window with no frame name.
- The current frame (i.e., the "menu" frame).
- The parent frame (which in this case is the entire page).
- Or the entire page, explicitly.
Enter the URL for the content you want to push. If you omit the "http://" from the front of the URL, these characters will be inserted automatically.
Click on the "Push content" button.

The content specified by the URL you entered will appear in the target you selected.

When the browser leaves this Web page, or if you push content to the current frame, the parent frame, or the entire page, the applet must be unloaded and therefore it will stop. At this point it will automatically unregister with Gubd, which will notify Gubshell, which will remove the client's name from the GUI's client menu. You won't be able to push content to the client again until that browser revisits your Gubcast-enabled page.

Three troubleshooting notes:

The Gubdemo HTML is static, so every client name is always "test". If multiple browsers visit your Gubdemo directory at the same time you will see multiple "test" clients and won't necessarily be able to distinguish one from another.
If there's a firewall between Gubd and Gubshell, Gubshell will fail to connect to Gubd unless traffic on TCP port 5108 is enabled in the firewall.
If you have problems running Gubdemo, check the Remarks for hints on what might be going wrong. Note that the Gubcast applet downloaded in the Gubdemo HTML tries to register with Gubd on port 4567 and receives content from Gubd on port 4568.

Hey, this is too complicated.

Okay, here's how to get Gubdemo running in about three minutes, without doing any web server administration at all. All you need is a connection to the Internet. (This section is all written in the assumption that you're in Windows, but the Linux [etc.] analog isn't hard to work out.)

Make a directory named "gub". Copy all three jarfiles (from the "lib" and "demo" directories) into it. Copy all the HTML in "demo/HTML" into it. Start two console windows, and cd to your "gub" directory in both of them. In one console window, enter this command:

java -classpath .\gubdemo.jar;.\gubcaster.jar Gubd

In the other console window, enter this command:

java -classpath .\gubdemo.jar Gubshell

Then double-click on the index.html file in "gub". Your browser should pop up with the Gubcast demo page displayed, and a new client named "test" should appear in the Gubshell window's client menu.

Finally, in the Gubshell window, enter "bottom" as frame name and "www.stepsoncats.com" as URL, and click on the "Push content" button. In the browser window, the bottom frame of the demo page should now display the Steps On Cats home page.