Zat Home
Documentation | Installation Guide

Spin™ Installation Guide

This manual covers installation issues on various platforms.

Table of Contents


The current version of Spin is much easier to install than previous versions.

Spin requires a JDK (Jave Developer's Kit) or SDK (Software Developer's Kit) to run, not just a JVM (Java Virtual Machine) or JRE (Java Runtime Environment) because it requires a Java compiler to compile scripts. Previous versions of Spin did not include the JDK because of licensing restrictions from Sun. This meant that you had to install a JDK yourself before installing Spin, and also led to a number of compatibility problems between Spin and the various versions of the JDK out there. In this release, things are better.

Spin uses an installer (InstallAnywhere from ZeroG) to make installing Spin as easy as possible. For most users, installing Spin simply consists of downloading the appropriate installer for your platform from the Spin download page, and then executing it. By default, the installer installs the appropriate version of Java for your platform, Spin, and the PointBase DBMS (DataBase Management System).

After you install Spin, we strongly encourage you to work through the examples in the Spin Tutorial. This will give you a quick introduction to Spin.

You can now use a download manager to download Spin.

The Spin download page has installation instructions for each platform.

Installation Files and Directories

Spin is installed into the directory you specified during the installation. This directory contains the following subdirectories:
Where any images, sounds, animations, and other asset files used by the example programs are stored.
Where all JavaBeans used as actors are stored. To add a new actor JavaBean to Spin, simply drag it into this directory and restart Spin.
Where all user-defined behaviors are stored.
Where JavaDoc documentation for JavaBeans are stored. If you add a new JavaBean to the beans directory, you can store its JavaDoc documentation here, and Spin will find it.
Where client-side example programs are stored. This is a convention only — you can put Spin projects and capsules anywhere.
Spin icons
The Jikes Java compiler from IBM. Installed on Windows only.
The Java Runtime Environment from IBM. This directory only exists if you used the Windows Spin installer that includes Java.
The PointBase DBMS (DataBase Management System). Used to develop database applications with Spin.
Where the Spin debug web server finds html files. The location of this directory can be changed using a Spin preference.
Where server-side example programs are stored. This is a convention only — you can put Spin projects and capsules anywhere.
Spin uses some Java code whose source is freely available. We include that source code here for you.
Spin uses this directory when "grinding beans" to hold intermediate results.
Files used to remove Spin from your system, including a log of all actions taken during the installation of Spin. This directory only exists on certain platforms.

The main Spin directory contains some .properties files that are used by Spin.

The main directory contains nine jar files used by Spin. LEGAL NOTICE: As described in the ZAT Binary License Agreement, in the file License.txt, the term "ZAT Components" includes the files zat.jar, zatlib.jar, and zatservlet.jar, as well as most of the files found in the "beans" subdirectory of the Spin installation. These ZAT Components may be redistributed with an application, applet, servlet, or component built using Spin, but they may not be used for any other purpose. The file ZatSQL.jar in the "beans" subdirectory may be deployed onto a single server, but if you want to deploy it onto additional servers, you must license it from Zat (or simply purchase additional copies of Spin). No other files in the Spin installation can be redistributed in any form. See the ZAT Binary Licence Agreement for more information.

Invoking Spin

The files lax.jar, Spin.exe, and Spin.lax are files used by LaunchAnywhere to launch Spin on Windows. On other platforms, the file names may be slightly different (e.g., on Macintosh, Spin.exe is just called Spin. You do not actually need these files to run Spin, they just make it more convenient. Spin is written entirely in Java, and the same program runs on all supported platforms.

You can invoke Spin directly. For example, on Windows, you can create a .bat file containing the following command (this should all be on one line):

java -classpath %classpath%;zat.jar;zatapp.jar;zatload.jar;zatlib.jar; zatservlet.jar;zatservletdebug.jar;jsdk.jar;swingall.jar;. zat.editors.Spin

A similar command could be used on UNIX in a shell script. On the Macintosh, a similar command — created using JBindery — is provided in the file Spin.bin, which you can expand using StuffIt Expander and use instead of the installed application file 'Spin'.

Using Spin with Java 2

The easiest way to use Spin with Java 2 (JDK 1.2) is to install Java 2 first, then install Spin. When you install Spin, the installer will ask you which version of Java you want to use. Select the Java 2 that you just installed. The only reason to run Spin on Java 2 is if you are using any components in a Spin project that require Java 2.

You can run the same copy of Spin on multiple versions of Java. To do this do not use the CLASSPATH or PATH system variables at all. Instead create a .bat file (Windows) or shell script (UNIX) to run Spin, as described in the previous section. Then use the -classpath option to completely list the files you want in your classpath, without referencing "%classpath%" (Windows) or "$CLASSPATH" (UNIX). Also specify the full path to the "java" or "jre" command, so you do not use the PATH variable either. You will need a separate file (.bat or shell script) to invoke Spin, one for each JDK.


There are two kinds of documentation that come with Spin. One is the Spin manuals, like this one. The other is the JavaBean documentation generated by JavaDoc, used by the Spin GetObjectInfo command to display information about JavaBeans used in Spin.

Spin Manuals

You can access the manuals online, in one of several ways:

GetObjectInfo Documentation

Spin can display documentation for any JavaBean component used as an actor in Spin. This documentation is generated by JavaDoc from the source for each component.

In general, Spin components come from three places:

  1. Components that come with Spin, including the HTML beans, visual beans like Text and Rect, and non-visual beans like Clock and SqlSelect.
  2. Components that come with Java, including AWT components like Button and Scrollbar.
  3. Components you add later, or that you write yourself.

JavaBean documentation is displayed using the Spin GetObjectInfo command. This command is found in both the View menu and the Actor menu. There is also a keyboard shortcut, Control-I (Command-I on the Macintosh), or you can use the right mouse button menu (Command-click on the Macintosh).

To display online documentation for a JavaBean, the GetObjectInfo command must be able to find the documentation:

  1. For the JavaBeans that come with Spin, documentation is automatically installed in the "docs" subdirectory of the Spin installation directory.
  2. For JDK documentation, Spin accesses this documentation from Sun's Web site.
  3. For JavaBeans you add to Spin (by placing them in the "beans" subdirectory of the Spin installation directory), you should add any corresponding JavaDoc documentation to the "docs" subdirectory of the Spin installation directory. JavaBeans you acquire should (hopefully) come with JavaDoc documentation, too.

JavaDoc documentation is always in HTML format, but there are two ways that this documentation can be named: using dot notation or using directories. For example, the Time JavaBean in the zat.misc package can be named zat.misc.Time.html, or it can be named zat/misc/Time.html (substitute \ for / on Windows, or : for / on Macintosh).

Spin can use either format. The Spin JavaDoc documentation uses directory based filenames, because the dot notation results in file names that exceed the maximum allowable file name length on some platforms.

Offline Documentation

The Spin manuals are normally accessed from Zat's Web site, and the JDK JavaBean documentation is normally accessed from Sun's Web site. Accessing the documentation online assures you that you are always viewing the latest version of the documentation. If you need to use Spin without an Internet connection, this can be problematic, so you can download and install a local copy of both kinds of documentation, if desired.

You can download a complete set of Spin manuals from the Zat download Web page.

To install the JDK JavaBean documentation, you you need to download it, install it, then set a preference so that Spin can find it.

First, you need to download the JDK documentation from Sun. This can be downloaded from Like all JavaDoc documentation it is in HTML format, and is identical for all platforms. If you are using Spin with another version of Java, such as Java 2 (JDK 1.2), you need to download its documentation instead.

Unpack this documentation into an appropriate directory, such as the docs subdirectory of the Spin directory, or (if you are using some other version of Java) the docs subdirectory of your JDK directory. The JavaDoc documentation we are interested in is in the "api" subdirectory of the unpacked docs directory.

Finally, you need to change a preference so that Spin can find this documentation. From inside Spin, go to the Edit menu and choose "Preferences". Set the Spin preference JDKDocsDirectory (in the General tab) to the "api" subdirectory of the JDK docs directory.

Installing New Components

Installing new components is easy in Spin. For simple components, you will only need to copy the components into the beans subdirectory of your Spin installation directory and restart Spin. If the components come with JavaDoc documentation, that documentation should be copied into the docs subdirectory of the Spin installation directory.

If the beans use any assets, they can be placed into the asset subdirectory of the Spin installation directory (but this is only a convention, and is not required).

If the components have any libraries, these will need to be installed onto your system using the instructions provided with these libraries. You will also probably need to set your system CLASSPATH to allow Java to access these libraries.

The next section covers how to install some fairly complicated components, the Quicktime components and associated libraries.

Installing QuickTime

Installing QuickTime is not especially difficult, there are just lots of steps.

First, you must have installed the latest version of Quicktime on your system. For playback you don't need the Pro version, the free version is fine. Note that there are versions of QuickTime only for Mac and PC, so if you are on some other platform, you're out of luck. For other platforms, you can try the Java Media Framework instead.

When you install QuickTime, be sure to install the QuickTime for Java libraries. You can also download and install QuickTime for Java separately. This is a set of Java classes that give access to QuickTime from Java. These classes must be added to your CLASSPATH so that Spin can find them.

At this point, you can access QuickTime calls from within Spin scripts, but what you really want is QuickTime-enabled JavaBean components. There are two sources for QuickTime components: from Elegant Chaos and from Tiger Island. These two sources have different capabilities. Finally, you need to install these components into the beans subdirectory of the Spin installation directory.

Reinstalling and Upgrading Spin

You can install a new version of Spin over an existing version. Of course, we highly recommend that you back up your existing Spin installation before installing a new version over it. You will also need to reenter your Spin registration key (and the email address you used to create that key).

Sometimes new versions of specific components can prevent you from opening an existing capsule you have built with Spin. While the JavaBeans component architecture provides facilities so that JavaBeans can automatically upgrade themselves to new versions, sadly, most JavaBeans authors do not implement this feature. For most JavaBeans, the only way around this problem is to open the capsule using the old version of the component, and manually remove all instances of that component. Then replace the old component with the new component in the beans subdirectory, and restart Spin. Finally, open your capsule and insert instances of the new component in all the proper places.


Spin includes a copy of the PointBase DBMS (DataBase Management System). This copy is for development purposes only, and cannot be deployed in a commercial application without first licensing it from PointBase. In addition, the free development copy is restricted to 5 MB total database size.

Spin installs several links for PointBase (in a directory, the start menu, or on the desktop, depending on what you chose when you installed Spin and what platform you are running on). These are:

Spin comes preconfigured for the PointBase DBMS. To use Spin with other databases, you will need to configure them in the file. Spin should work with any database that has JDBC drivers. See the Spin Database documentation for more information.

6 March 2000 — wm
Feedback to