© 2000-2003 A-Square, Inc. Cambridge, MA
We shall here go through some of the details of how a Rart universe can be displayed on a webpage, and seen over the Internet running in an applet environment. We will study the applet tag in HTML and we will also discuss jar-files for efficient distribution of applets.
The Applet Tag
About jar-files
Distribution of a Rart Universe
Display of a Rart Universe
Many of the readers probably already know about webpages and how they are described in HTML, the hypertext markup language.As far as the display and distribution of an applet is concerned, we do not have to go into all the mysteries of HTML, but have to concern ourselves with the applet tag and what it can contain.
An example of a simple applet tag is the following (Taken from Exercise 1a):
<APPLET CODE="Banner1.class" WIDTH="390" HEIGHT="114"
ALIGN="MIDDLE" ALT="( With a java enabled browser you would see animation here)">
</APPLET>
APPLET and /APPLET delimit the applet tag. The < and > are necessary and critical. However, upper and lower case has no significance as far as HTML is concerned.
Of the things that are in the applet tag, strictly only three items are absolutely neccessary. CODE, WIDTH, and HEIGTH. CODE gives a reference to the applet class that is to be executed, here "Banner1.class". We put the filename in double qoutes to ensure there is no case-related misunderstanding.WIDTH and HEIGHT give the size of the rectangle where the applet is displayed in pixels. In the regular browsers these sizes (and the other entries for positioning on the page) are set once and for all. In an appletviewer, however, the applet window may be resized and it is up to the applet code to accommodate such changes.
A 17" monitor may offer a screensize of 1024 x 768 pixels. However, that is not what is available to the applet, since the browser usually has toolbars and buttonbars only some of which can be turned on and off. In any case, you can if you wish change the size of the window by editing the Applet tag. The ALIGN obviously serve to locate the applet on the web page. But all this you find out in a web design book so don't worry about it now.
In the case of this applet tag, we have also added some text, after the ALT which would show if the browser is smart enough to know about applet tags but not smart enough to display applets. In general there are not very many of these browsers around except for the case that you have a Java capable browser where Java is disabled. Both Netscape Navigator and Internet Explorer are normally enabled for release 4.0 up. AOL 5.0 is also Java enabled without the capability for disabling which gives considerable satisfaction to me and an indication of the general acceptance of Java.
Java was introduced as an Internet oriented language and the ability to display Java applets was a great boost to the language (Actually the great excitement started when Rolf Andreassen of Netscape announced that Netscape would support Java and applets on May 23, 1995). However, it was quickly discovered that if you have any kind of complex applet, the start and stop when downloading each necessary class slowed the spead of download considerably. The solution was to consolidate all classes and other resources needed in a zipfile, which, as it is used in Java is actually called a jar-file.
The way it works is like this. You create a jarfile by calling the jar tool which is part of the java toolset and included in jdk. The way you call it from the command line is, with Exercise 2b as an example:
jar -cvf ex2b.jar *.class *.gif
This makes a jarfile called ex2b.jar which consists of all fileswith the class extension and all files with the gif extension in the folder where the command is invoked, the current folder. In the case of Exercise2 this would be the four class files, Logo, IEEELogo, ASquareLogo and the applet Banner2b as well as the IEEE logo as a gif-file. Complete scripts for the creation of most of the jar files used in the Introduction to Java tutorial are included in the Wintel, WindowsXP subfolder in the PlatformSpecificScripts folder. For further details on how to make jar-files you should consult your Java reference source.
Once you have created a jarfile which includes your applet class you can refer to it in the applet tag by using the ARCHIVE attribute. In the case of Exercise 2b the modifed applet tag now reads as follows
<APPLET ARCHIVE="ex2b.jar" CODE="Banner2b.class" WIDTH="390"
HEIGHT="114" ALIGN="MIDDLE" ALT="( With a java enabled browser you would see animation
here)">
</APPLET>
The inclusion of the jar file reference with the ARCHIVE attribute
is straight forward. Note, however, that you still have to tell the system which of the class files is the actual
applet by using the CODE attribute.
As we have seen in the Tutorial starting with Exercise 3, a Rart universe can be displayed running in an applet rartrunner. However, we now have many files involved and so we will take advantage of the jar-file sysem of packaging.
Let us first take a look at the packaging of the rart software. Fundamental to all Rart activities is a package rartbase which consists of the following classfiles:
AboutDialog, used to display information about the universe.
Debug, used to provide trace outputs for debugging.
RR, the mother of all rartrunners.
RRL, the simplest possible rartrunner for display of a universe on an applet on a webpage, extends RR.
ShowTextCanvas, used to provide text in dialogs in a unified way.
Universe, the mother of all Rart universes.
uParameter, defines the commonality of all uParameters.
A second package of Rart classes is called rrlet. It contains, among other classes, the rartrunner RRlet which is an applet which can display a Rart universe completely, that is so that the observer may modify any uParameters. If you wish to observe a unverse over the Internet executing under RRlet, you need to download the universe with its associated classes and other resources as a well as the two packages rartbase and rrlet.
The third and final Rart package is called rr11. It contains a fair amount of code but is normally distribted on a CD. rr11 includes the rartrunner RR11, (RR11 extends RRlet) which can execute a Rart universe as an application with the ability for the observer to make modifications to uParameters. Under RR11, the observer may also freeze views and print them out. Classes in rr11 require both the other packages, rartbase and rrlet.
With RDK 2.0, all software, except for the universes and the source code, go in the three packages. The following table lists the package, the number of classes in each package and the number of bytes, un compressed and compressed.
|
PACKAGE |
Nr of Classes |
Size uncompressed |
Size compressed |
| rartbase |
7 |
24.1 KB |
15 KB |
| rrlet |
7 |
19.5 KB |
12 KB |
| rr11 |
16 |
44.1 KB |
27 KB |
The byte code for a typical universe is perhaps 10-15 KB uncompressed. If the code is combined with rartbase and the universe is displayed in RRL, (See Exercise 3a-3c) the jar file takes a total of 21 KB. In Exercise 3d you add another class, but also the IEEE logo, (19 KB uncompressed) for a total of 41 KB in the jar. Compare these numbers with the typical MS Word documents with in the order of 20 KB or an HTML document with 10-12 KB. The conclusion must be that the compression is efficient and that Rart universes can be be seen also over slower Internet connections. Since they are combined in one file, the download of 21 KB should take no more than 5 - 10 seconds over an average phone-line.
When we wish to execute a Rart universe in an applet, we invoke it in an applet tag. However, the actual applet is the rartrunner, either RRL or RRlet. The name of the universe, that is the name of the class of the Rart universe, is supplied as a parameter in the applet tag. To execute the Eggs4a universe in RRlet, using the default value of any uParameters, the applet tag reads as follows:
<APPLET ARCHIVE="ex4a.jar" CODE="rrlet.RRlet.class" WIDTH="760" HEIGHT="450"
ALIGN="BOTTOM">
<PARAM NAME="UNIVERSE" VALUE="Eggs4a">
</APPLET>
Note, that the RRlet.class is referenced in the CODE attribute as rrlet.RRlet.class since RRlet is, in fact. part of the rrlet package.
When a Rart universe is executed in an applet, the window size is fixed once and for all in the applet tag. However, the rartrunners are programmed to adjust themselves dynamically to the available window which can be seen when executing a universe in an applet viewer or, perhaps more significantly when it is executed in an application..
In the applet tag, you can also supply a value for DEBUG_LEVEL which by default is 0.. Both the rartrunners and the universes can have built in trace statements that are normally ignored. However, if you set the DEBUG_LEVEL to be 1 or up to 5, you activate the statements, and you may get useful output, that appears on the enabled Java console for browsers or in the activating command window for the appletviewer or the Rart application. You can read more about the Debug class and how it is used elsewhere. The Eggs universe shows how to set the debug level for the universe inside the universe code. This is appropriate when developing a universe. However, if you set it in the Applet tag, you will affect also the RDK classes.
Another important use of the applet tag for a universe is to supply it with startup values other than the default values for uParameters. In order to provide a value for a uParameter, you need to know what is the index for the uParameter in the uPs array. Please check out Section 3, uParameters as used in the universe, in the listing of Universe. You need to know not only the index assigned to the uParameter. The assignement is made as the first parameter in the uParameter constructor. You also have to know what is the allowed range of parameter values for uParameter type one, or the desired index to the array of alternative selections for type two. (Actually, if you should give a value outside the allowed range nothing bad happens but the value is forced to within the allowed range, which may not be what you intended, but does not brake anything). As an example of customizing the startup HTML for the Eggs universe, the following is the HTML used to start up the Eggs4a universe with a square display right on the page, dark gray background color, and blue eggcolor. (Note the convention for supplying comments inside an HTML document!).
<APPLET ARCHIVE="ex4a.jar" CODE="rrlet.RRlet.class" WIDTH="450" HEIGHT="450" ALIGN="RIGHT">
<PARAM NAME="UNIVERSE" VALUE="Eggs4a">
<PARAM NAME="PARA5" VALUE="1">
<PARAM NAME="PARA6" VALUE="3">
<!-- This is the format for an HTML comment -->
<!-- Egg-color Blue -->
<!-- Background dark grey -->
</APPLET>
The point of the applet and the applet tag is, of course that the universe may be displayed on a webpage and over the Internet. If you have the code for the universe on your computer, you may also display the code in the Applet Viewer. See, for example, Exercise1. You will need some kowledge about how to run programs on your platform or you can use the method of the exercises which involve the execution of a simple platform specific script.
With an application, just as with the appletviewer, you have to work with your platform. The RART CD has a folder, Rart Application, which contains everything you need in order to execute a universe as an application. However, some clarifications are in order and these have to be platform specific. In principle, however, we relegate the platform spacific information to a script that we called RunRart. It makes certain assumptuions about the availability of Java. In particular, we assume that you are able to run the application using JDK 1.1.8, which we know you have installed from the RART CD. The RunRart script is as follows for Wintel/WindowsXP if you run under JDK 1.1.8, it is called RunRart118.bat:
path C:\"jdk1.1.8"\bin
SET CLASSPATH=C:\jdk1.1.8\lib\classes.zip;C:\com\rart\classes.zip;.
java -version
java rr11.RR11
ECHO *** Press Any Key to Continue ***
PAUSE >NUL
The path takes you to the JDK1.1.8 directory, where java.exe is in the bin. The CLASSPATH brings in the JDK classes as well as the com\rart\classes.zip where we have stored the rart packages, includung rartbase, rrlet, and rr11. On the RART CD is a folder named RartApp2Go which includes some of the existing universes, including, the ThreeBalls universe, which has not been discussed elewhere. The folder includes the universe classes, some resource files and something that is needed for the application, for each universe a file with the name (classname) of the universe and the extension unv. This is used by the RR11 rartrunner to determine what universes are available. Note, that none of the rart packages have to be in the folder, they are referenced through the classpath variable.
Another very similar script is RunRartJ2SE.bat which looks as follows:
path C:\jre\bin
SET CLASSPATH=C:\jre\lib\rt.jar;C:\com\rart\classes.zip;.
java -version
java rr11.RR11
ECHO *** Press Any Key to Continue ***
PAUSE >NUL
This script assumes that you have the Java run time installed, as noted at C:\jre. and requires a corresponding modificaton to the classpath. There is, there should be, no differences between the universes running under the one runtime or the other. And this is indeed the case for all the universes included, except, I regret to say, the TreeBalls universe which works under RunRartJ2SE, but not under RunRart118. One day, we will find out why, I hope. Note, that since we developed the universes using JDK 1.1.8, it cannot be the case that we have used facilities or classes avilable later than JDK1.1.8.
You start up the Rart application by executing the RunRartxxx script, which starts up the rartrunner RR11, In general, you get a welcome screen (actually a close variation of the Banner2 universe) and you click to get a file selectionbox from where you can select among provided universes, that is universes where the class name is also provided with the unv extension.
However, when starting up RR11, you may also provide certain information on the commandline. On the command line you give the "name" of the parameter followed by = and the value as a string: eg WIDTH = "600 ". It appears that it is necessary to insert an extra space after the value of the parameter. The parameter name is not case sensitive, but the value is.This information may include, the name of a universe you would like to start up, DEBUG_LEVEL and HEIGHT and WIDTH in pixels of the window. WIDTH with default 500, and HEIGTH with default 400. Actually RR11 will change to the actual size of the window during the first cycles. But you can, of course change the size of the window at any time during execution. Normally the A-Square logo, classname "A2", is the default startup universe. However, by giving a different name to the parameter UNIVERSE. If you insted are working on a universe Planes, you include the string UNIVERSE="PLanes" on the command line. Debug level can be set from the command line, eg DEBUG_LEVEL="2", if you wish to change the level from its default value( which is 0) to 2. If you have more than one parameter on the command line, the parameter settings are separated with commas.
If you wish to execute the Flakes universe, with a debugvalue of 2, the fourth line of RunRart should read
java rr11.RR11 UNIVERSE="Flakes ",DEBUG_LEVEL="2 "
I just did it; and loo and behold it works! With good paper and a good printer you can make youself some exeptionally nice and big flakes. Make the screen square, make only one flake and make the complexity high. You may have to wait some, but then it comes, a gorgeous flake to decorate your otherwise uninspiring office. Cheers.