Applet Drawing Library: adraw.jar

The Javadocs for the adraw library.

The adraw package defines the abstract class World that provides the same programmer's interface as the idraw package. That means that any program written with the idraw package can be converted into an applet. To construct an applet the programmer must do the following:

Define a class that extends WorldApplet class as shown in the Applet Java Code section below.
Upload the libraries the applet uses - or determine their location on the web.
Upload the code for this applet to the server directory.
Create a simple html file that launches the applet and upload the file.

Applet Java Code

To convert the World that uses the idraw library into an applet the programmer must change all import statements for the idraw library to similar import statement for the adraw library and define one additional Java class that extends the WorldApplet class.

The WorldApplet class contains two fields that represent the size of the world: WIDTH and HEIGHT. The programmer needs to implement two abstract methods: getNewWorld and setWorldSize.

The getNewWorld method produces an instance of the programmer-defined world that starts the animation. This is the same as the instance of the world that invokes the bigBang method in the imperative and functional world.

The setWorldSize method sets the WIDTH and HEIGHT variables to the desired applet display size for this world (the size of the Canvas that will be shown). Again, this is the information required by the bigBang method in the imperative and functional world. In our sample the size is set to a fixed value. If the programmer desires some flexibility on the size choice, it must be done with care, making sure the world size and the selected applet display size remain the same. The WorldApplet class prevents the programmer from setting the world size to be smaller than 200 by 200. There is no need to set the speed, as the applet provides a slider GUI field that allows the user to set the speed prior to running the game.

// Relevant parts of the WorldApplet class:
abstract public class WorldApplet extends JApplet{
  protected int WIDTH;
  protected int HEIGHT;
  abstract public World getNewWorld();
  abstract public void setWorldSize();
}

The applet is now ready to run and can be shown in AppletViewer when run as an applet from the current IDE or from the command line.

Uploading the libraries

An applet code and the html file that describes the web page in which the applet is embedded can be uploaded to your server and be then seen by the whole world wide web. For the rest of the description we assume that you have made a folder/directory named MyApplet on this server. Assume the URL for this folder is http://www.myname.net/MyApplet

Before we can write the html code that displays the applet in the web page, we need to know where the applet can find the applet code and the libraries the code may use. The libraries the applet is using can be accessed in two different ways. We can decide to upload the jar files directly onto our server, or we may refer to the place on the web where the archival copy of the libraries is saved.

For the first option, every jar file must be saved in a directory whose name matches the name of the package to which the file belongs. If the xlib.jar file belongs to a package with the name mylib.util then we must create in the MyApplet a subdirectory sequence MyApplet/mylib/util and save the xlib.jar file in this directory. For the JavaLib packages we need to build the following directories (and files in them):

MyApplet/adraw/adraw.jar, MyApplet/colors/colors.jar, MyApplet/geometry/geometry.jar, and MyApplet/tester/tester.jar, if it is used (the test code may be deleted from a published applet - for brevity.)

For the second option we only have to know the URL for a location where the library files are accessible. Make sure this is a permanent depository that will not disappear in a couple of months. Also, if the files stored at the URL location are likely to change and you worry that your applet may no longer be compatible with the updated version, you may decide that option one is a better choice for you.

The permanent website for these libraries is located at the following URLs:

http://www.ccs.neu.edu/javalib/Downloads/v1.0/adraw/adraw.jar
http://www.ccs.neu.edu/javalib/Downloads/v1.0/colors/colors.jar
http://www.ccs.neu.edu/javalib/Downloads/v1.0/geometry/geometry.jar
http://www.ccs.neu.edu/javalib/Downloads/v1.0/tester/tester.jar

New releases will be saved in directories with new version numbers.

Upload the applet code

We present four different ways for uploading the applet source code:

The applet expects a compiled code (the .class files). You may upload all .class files to the MyApplet directory - but that is quite messy.
A more palatable option is to make a bin subdirectory in the MyApplet directory and save all class files there.
A better option is to package all the classes that comprise your world into the myworld.jar file. We assume here that the classes have been defined in the default package. Upload the file myworld.jar to the directory MyAppletFolder.
Finally, if you have defined your world in a package (say named game) then the name of your jar file must be game.jar and you must upload it into the MyApplet/game subdirectory.

The applet html code

The applet can be presented as a standalone web page, or as a part of a collection of applets, or can be embedded in a web page with other contents. Edit the html code at the end of this section with information specific to your applet at all places shown in italics. Provide directions for the user that explain how to play your game, or how to use your world.

Specifying where the browser can find the applet source code.

The line

code="MyWorldApplet.class"

indicates that the class MyWorldApplet defines the class that extends the WorldApplet class and the applet execution starts there. Replace MyWorldApplet.class with the name of your class that extends the WorldApplet class. You supply the name of this class regardless of whether your source code is saved as a collection of .class files or as a .jar file.

For the four options for how to save your source code described above we provide sample code for locating the source code within the applet html file:

The MyApplet file contains the .class files
```
<applet
code="MyWorldApplet.class"
```

The .class files are saved in the directory MyApplet/bin

<applet
codebase="./bin/"
code="MyWorldApplet.class"

The code for the applet has been saved as myworld.jar file in the MyApplet directory and has been defined in the default package
```
<applet
code="MyWorldApplet.class"
archive="myworld.jar, ...
```
The code for the applet has been saved as game.jar file in the MyApplet/game directory and has been defined in the game package
```
<applet
code="MyWorldApplet.class"
archive="./game/game.jar, ...
```

Specifying where the browser can find the applet libraries

The next part tells the web browser where to find the .jar files, i.e. the libraries and possibly the .jar file for the applet source code.

archive="myworld.jar,     
         ./adraw/adraw.jar, 
         ./geometry/geometry.jar, 
         ./colors/colors.jar"

Omit the part myworld.jar if you have saved your code as .class files (see above).

If you wish to refer to archival library collection at a specific web site, you may write:

archive="http://www/some-server.abc/adraw/adraw.jar, 
         http://www/some-server.abc/geometry/geometry.jar, 
         http://www/some-server.abc/colors/colors.jar, 
         http://www/some-server.abc/tester/tester.jar"

or specify some other web site where your libraries are found.

The last part of the applet tag in the html file gives the total size of the applet. The size given here is the size of the border around your world - make is at least 20 pixels bigger than the size given in the Java code.

Save the file as MyAppletWorld.html in the MyApplet directory. Access the applet on the web at URL http://www.myname.net/MyApplet/MyAppletWorld.html

Sample complete html file:

<html>
  <head>
    <title>
      Web page title: My applet
    </title>
  </head>
  
    <body>
      <h2> My Applet Header</h2>

<p>This is how you play my game. 
      Please, use the slider to set the clock speed 
      before starting the game.</p>

<applet
code="MyWorldApplet.class"
archive="myworld.jar, 
         ./adraw/adraw.jar, 
         ./geometry/geometry.jar, 
         ./colors/colors.jar"
width="400"
height="400">
</applet>

     <hr></hr>

... additional webpage contents ...

   </body>
  </html>

Directory structure

The directory structure for this applet looks as follows:

MyAppletFolder       ... the main applet folder
   MyApplet.html     ... the html file defined above
   myApplet.jar      ... a jar file that contains 
                             MyWorldApplet.java, 
                             MyWorld.java,
                             and all other files my world uses
   adraw             ... a subdirectory
        adraw.jar    ... the Applet world library
   geometry          ... a subdirectory
        geometry.jar ... the geometry library
   colors            ... a subdirectory
        colors.jar  ... the colors library