BoidsDemoEai:  ReadMeDemo.txt

Revised:       25 July 97

Authors:       Don McGregor, Kent Watsen & Don Brutzman

QuickStart Instructions:

1.  Edit:      BoidsDemoEai.html to match your machine's IP address
               (from the value 131.120.63.206)
               (unfortunately 127.0.0.1 localhost doesn't work)
               
2.  Edit:      ../Bridge/defaultBridge.bat to match your machine's IP address
               (from the value 131.120.63.206) (sound familiar?)

3.  Close:     All versions of Netscape.  Java class libraries seem to be
               persistent and don't get along very well either.
               
4.  Launch:    defaultBridge to connect multicast port to unicast Netscape

5.  Launch:    Netscape to default page, NOT the BoidsDemoEai.html page

6.  Netscape:  open Java Console if you want to see trace messages while starting

7.  Netscape:  go to File menu, open local file mil/navy/nps/JavaViaEai/boids_demo.html
               (for some stubborn reason, opening from a bookmark seems to fail).


This is an EAI-based demo of DIS, Java, and VRML operating together in a 
minimal virtual world.

Two computers are displaying a basic VRML scene. Each computer controls 
a "boid" in the VRML scene.  (We have a couple guys from New Joisey around
here.  That's how they describe flying wildlife--"lookit dat boid!")  Each boid 
periodically updates its position to the rest of the network by sending out 
DIS packets.  The java applets in the browser listen for the DIS packets and 
update the VRML display accordingly via the EAI interface.

As you start up the html file, there are three basic regions: the VRML display
(The CosmoPlayer/WorldView plugin); the world applet, which displays two buttons and
a framerate field; and the Network Interface Unit applet, which simply flashes
red when it sends a packet and green when it receives them.

The VRML display is simply a VRML plugin on the web page. There's a basic background,
just enough to give a little viewing perspective. 

The region below this is the "World" applet, with a button for adding or removing
your own boid to the VRML file. This applet also implements the physics of the
scene--keeping track of what boid is where, updating the position of the boids,
etc. There's a framerate display; I've seen this broken under certain configurations.

The small flashing square is the Network Interface Unit (NIU). This applet is
responsible for handling communications with the rest of the world. It's just
a couple of sockets, one for reading DIS packets and one for writing them. Right
now these are unicast sockets, since multicast didn't make it into the 
official 1.02 Java spec. Also, Netscape 3.x doesn't do multicast.

An overview of the demo is as follows:

THE HTML FILE

The HTML file used to start the demo has a few non-obvious traits. The vrml
region is started up in the usual manner:

<CENTER>
<EMBED SRC="world.wrl" border=0 width="700" height="500">
<P>

Where the height and width are the area taken up by the VRML display in
the browser.

The World applet contains some important command-line parameters.

<applet name="World" codebase="" code="World.class" mayscript width="360" height="30"> 
<param name=ownshipEntityID value="0 1 2">
</applet>

The "codebase" command tells the browser to look in the world directory beneath
the current location of the html file. "mayscript" allows the applet to
perform JavaScript scripting; a small portion of the applet requires this
in order to get a handle to the VRML plugin. The width and height define
the area taken up by the panel. The final entry is a parameter passed to
the java applet, much like a command line parameter. The "ownshipEntityID"
parameter defines the DIS entity ID to be used for the boid created. Every 
entity in DIS must have a unique ID, defined as a triplet of shorts. On the
other machine in this demo, the entity ID must be changed in the HTML file;
the value "0 1 1" works fine.

The final area of interest in the html file relates to the NIU applet.

<applet name="NIU" codebase="world" code="NIU.class" mayscript width="20" height="20"> 
<param name=listenSocketNumber value="8007">
<param name=sendSocketNumber value="8008">
<param name=sendDestHost value="127.0.0.1">
<param name=sendDestSocket value="8004">
</applet>

The parameters passed in are the socket numbers used to read and write. 8007 and
8008 are sockets used by the applet itself for reading and writing. Socket
8004 is the socket used by one of the datagram bridges, as above. The sendDestHost
value is the machine we are sending to. In this case, we're actually sending
packets to the same host, to the bridges running on the same machine (see below). 
NOTE: one would expect that a hostname, such as madison.stl.nps.navy.mil would work here.
In fact, I've seen problems with this not working, for unknown reasons, perhaps
related to DNS. To use a host name you might have to make an entry in the
Windows LMHOSTS file.  Using the IP number always seems to work, though.
127.0.0.1 is Internet-wide default for localhost.

THE DEVELOPMENT ENVIRONMENT

General Configuration

The demo was performed using Netscape Navigator 3.01 and Cosmo Player from SGI. 
The Java JDK 1.1.1 release is required to run the datagram bridges from the
command line, at least if you want to use multicast. It's available from 
http://www.javasoft.com. The demo will NOT work under Netscape Communicator
Beta3. There seems to be some problem with the VRML plugins and EAI. Don Brutzman
has used World View and Netscape 3.01 with success.

The environment variables CLASSPATH and PATH need to be correctly set. Assuming
default installation points, they should look something like this:

CLASASPATH=c:\java\classes\vrml;c:\users\mcgredo\Java;.;c:\Program Files\Netscape\Navigator\program\Java\Classes\java_301

NOTE: I've seen problems with the above classpath. For some reason the netscape java_301
file seems to cause problems with the JDK javac compiler, the symptoms of which are an
error message when attemting to compile anything that says something about "unable to
initialize threads". One workaround is to remove the java_301 reference from the classpath,
then get Netscape Communicator and use the java classes in that, instead. If you do this, 
the path to the file (if Communicator is installed in the default location) is

c:\Program Files\Netscape\Communicator\Program\Java\Classes\java40.jar

Any pointers as to why the javac compiler blows up on the netscape classes would
be welcome.

The c:\java\classes\vrml entry in the classpath is required for the EAI classes of 
Cosmo Player.

c:\users\mcgredo\Java is the directory above the mil\navy\nps directory
hierarchy. This is required to recognize the various packages beginning
with mil.navy.nps.

The ".", or current directory, is included on general principles. This will allow
the javac compiler to pick up default package classes in the current directory.

The Netscape Navigator directory is included to bring in the various Netscape classes
required to interact with the browser, such as JavaScript.

The path variable is fairly straightforward; it needs to include the JDK binaries
directory, so that things such as the datagram bridges can be run from the command
line. Including c:\jdk1.1.1\bin in the path should do it.


DATAGRAM BRIDGES

There's a nasty bit of kludgery involved here to 1) bypass the java security
sandbox, and 2) get multicast capability.  

Normally the security manager prevents an applet from opening a
socket to an arbitrary machine. An applet can, however, open a socket to
the same machine it is running on; furthermore a Java application can do
whatever it likes, since it doesn't have the same security restrictions as
an applet.  So the strategy here is to implement a Java application "Bridge",
basically just a repeater; it accepts packets on one socket and sends them out
on another socket. The sandbox-free java application can listen and send to
any machine on the net, and the applet can talk to the application, since it's
on the same machine. By taking this extra configuration step we can bypass
the security restrictions.


This has the added benefit of allowing us to read multicast
packets in browsers that don't use Java 1.1, such as Netscape 3.x and MS Explorer.
The bridge can be implemented in the JDK 1.1 release, which includes multicast. The 
bridge reads on a multicast socket and writes on a unicast socket, which the browser 
applet can read.

A block diagram looks something like this:


    HOST A (madison)                          HOST B (pinafore)

  +------------+                     +----------------------+
  | Applet A   |                     | Applet B             |
  +------------+                     +----------------------+
8007^    |8008                           ^8007         |8008
    |    |                               |             |
    |    |8004                           |8005         |
    |   +--------+ 8001         8002+--------+         |
    |   |Bridge 1|----------------->|Bridge 3|         |
    |   +--------+                  +--------+         |
8005|                                                  |8004
    +-------+ 8002                            8001+--------+
    |Bridge2|<------------------------------------|Bridge 4|
    +-------+                                     +--------+



Applet A is running on host madison, and applet B on pinafore. Applet A
can't directly talk to Applet B due to the sandbox restrictions.
But applet A can talk to other applications running on the same
machine, namely the two bridge applications. These bridge applications,
in turn, talk to corresponding bridge applications on the other
host, which Applet B can communicate with. The numbers on the diagram
correspond to socket numbers used. (More on this later.)

The applet, in this case the NIU, has one socket for reading and
one for writing DIS packets. 

The bridge applications must be started up manually on each machine. 
The parameters passed into the application are:

java mil.navy.nps.bridge.BridgeHarness -?
Command line options:
  -inputSockType <unicast|multicast>
  -inputSockMcastGroup <multicast group>
  -inputSockNo <sock no>
  -outputSockType <multicast|unicast>
  -outputSockMcastGroup <multicast group>
  -outputSockNo <sock no>
  -destMachine <desination machine>
  -destSockNo <sock no>

The socket number the bridge reads from, the socket number it writes to,
the machine it writes to, and the socket number on that machine are all
passed in. Eg, the bridge on madison that handles writing to the remote applet
on pinafore--bridge 1 in the diagram above--would be started up as follows:

java mil.navy.nps.bridge.BridgeHarness -inputSockType unicast -inputSockNo 8004 
-outputSockType unicast -outputSockNo 8001 
-destMachine pinafore.stl.nps.navy.mil -destSockNo 8002

This accepts packets from the local applet on socket 8004, and writes them
out on socket 8001, destined for the machine pinafore and socket number
8002. Note that Windows 95 has a brain-damaged command line that accepts
a limited number of characters. You may run out of space while typing all
this in. If this happens, you can just place the command in a batch file
and run that.

Bridge 2, which accepts incoming packets from pinafore and passes them on
to the applet running on madison, would be started up this way:

java mil.navy.nps.bridge.BridgeHarness -inputSockType unicast -inputSockNo 8002 
-outputSockType unicast -outputSockNo 8005 
-destMachine madison.stl.nps.navy.mil -destSockNo 8007

Which reads on socket 8002 and writes on socket 8005 to the destination machine
madison and socket 8007. 

A similar pair of bridges has to be set up on pinafore. With these sets of
bridges running, the applets can communicate via DIS packets.

The socket numbers used here are completly arbitrary. You can use any number
you like, so long as they all match up and they are all above 1024. (Sockets
lower numbered than this are restricted access in many Unix environments.)