Installing and Using Java Netrek

Installation

Java imposes a lot of restrictions on the applets embedded into web pages. One of these restrictions is that an applet can connect only to the Web server from which it was downloaded. Thus, if you wish to set up pages which use the Netrek Viewer, you must install Java Netrek in a directory accessible by your server.

Suppose, for example, that the web server you use can access your ~/WWW directory and its subdirectories. Let's say then that you want to install the code in the directory ~/WWW/netrek/classes.

A number of universities and institutions such as CMU, Stanford, and MIT have based their computer systems on the Andrew File System. If your site supports AFS, you are in luck, as you will probably have direct access to the original Java Netrek code. All you have to do in that case is make a symbolic link:

 % ln -s /afs/athena.mit.edu/user/t/t/ttonchev/java/classes ~/WWW/netrek/classes

If you do not have AFS connection to MIT, the above approach will not work. You will instead have to create the ~/WWW/netrek/classes directory and then download and uncompress this ZIP file in there.

With this, the installation is complete.

Using the applet

Placing the applet in web pages

You can embed the Viewer applet into a web page by using the <APPLET> tag. Suppose, for example, that your page is situated in the ~/WWW/netrek directory, the Java Netrek code is installed in ~/WWW/netrek/classes, and the recording you want to present is ~/WWW/netrek/classes/recordings/rewl.prec. Here is the code you have to place in your HTML file:

	<APPLET	CODEBASE="classes" 
	        ARCHIVE="NetrekClasses.zip" 
	        CODE="viewer.class" 
	        width=1003 height=620>
	<PARAM NAME=RECORDING VALUE="classes/recordings/rewl.prec">
	Your browser does not understand Java, sorry...
	</APPLET>

The meaning of the above tags and parameters is the following:

CODEBASE is the URL of the Java Netrek classes.
ARCHIVE is a new Netscape 3.0 specific tag. It allows the browser to download all the relevant classes at once using the given zip file. The value of this tag should always be the name of the zip file you downloaded, or "NetrekClasses.zip".
CODE is an URL relative to CODEBASE and identifies the class to be executed. Its value must always be "viewer.class".
WIDTH and HEIGHT give the size of the applet as it will appear in the browser.
The value of the RECORDING parameter is the URL of the netrek recording to be replayed.
Finally, any text between <APPLET> and </APPLET> will be ignored by a Java enabled browser, but will be displayed by browsers which do not understand Java.

Designing pages which use the applet

Unfortunately, there are some limitations in respect to how pages using the applet should be linked. As mentioned in the specifications, Java is currently fairly inefficient. One particular problem is that Netscape keeps all active applets in the same virtual machine. This means that if you load a document that embeds the viewer, then click on a link and load another document that embeds the viewer, and so on, the applets will run more and more slowly until eventually Netscape will "crash" as Java runs out of memory.

To avoid this problem you should design your pages so that the user has to press the "Back" button of the browser to go to the previous page. Have a look at the examples document to see what I mean.

Also, try to avoid placing several viewers in the same document. It is usually not a problem, but I don't think anyone can or wants to look at two recordings at once anyway :)

Customizing the applet

You can modify the appearance and behaviour of the applet by giving it different parameters as arguments. For example, the applet is told which recording to play by setting the RECORDING parameter as shown above. A parameter can be set by placing the following tag between <APPLET> and </APPLET>:

<PARAM NAME=parameter_name VALUE=parameter_value>

The Netrek Viewer applet understands the following parameters:

Parameter Value Type Default Description

RECORDING URL none Required! The netrek recording to be replayed. Relative to the document URL.

IMAGELIB URL "ships.dir" The image library used by the applet. This URL is relative to CODEBASE.

VIEW One of ALL, TACTICAL, GALACTIC ALL The view mode. States whether to show the tactical map, the galactic map, or both.

OBSERVER One of YES, NO NO States whether the recording was made as an observer. This parameter may be set automatically in the future.

START Positive integer 1 The packet to start replaying from. Could be used to skip the pre-game period.

DELAY Positive integer 160 The desired interval between frames in milliseconds. Adjust this value if the game has not been recorded with 5 updates per second.

Parameter	Value Type	Default	Description
RECORDING	URL	none	Required! The netrek recording to be replayed. Relative to the document URL.
IMAGELIB	URL	"ships.dir"	The image library used by the applet. This URL is relative to CODEBASE.
VIEW	One of ALL, TACTICAL, GALACTIC	ALL	The view mode. States whether to show the tactical map, the galactic map, or both.
OBSERVER	One of YES, NO	NO	States whether the recording was made as an observer. This parameter may be set automatically in the future.
START	Positive integer	1	The packet to start replaying from. Could be used to skip the pre-game period.
DELAY	Positive integer	160	The desired interval between frames in milliseconds. Adjust this value if the game has not been recorded with 5 updates per second.

The VIEW parameter can significantly change the dimensions of the applet. As applets cannot resize themselves within Netscape, it is important that you set the applet size correctly within the <APPLET> tag. Here are the suggested dimensions for the different values of VIEW:

VIEW WIDTH HEIGHT

ALL (default) 1003 620

TACTICAL 503 620

GALACTIC 500 580

VIEW	WIDTH	HEIGHT
ALL (default)	1003	620
TACTICAL	503	620
GALACTIC	500	580

Using the editor

The Netrek Editor is a Java application. It can be executed only if the Java Development Kit is installed.

Once you have JDK installed, you have to set the environment variable CLASSPATH to the path of the Java Netrek classes. Given the setup suggested above, you should type the following (assuming csh):

 % setenv CLASSPATH ~/WWW/netrek/classes

Having done that, you will be able to run the editor. Its command line syntax is the following:

 % java editor [-obs] [-lib <imagelib>] <recording>

where both <imagelib> and <recording> can be file names or URLs. The -obs option enables observer mode, and the -lib option sets the path to the image library.

When run, the editor will allow you to replay the recording you have given it as an argument, and let you mark and save fragments to disk.

[Introduction] [Specifications] [Examples] [Source]

ttonchev@mit.edu