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
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
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).
- On the Windows platform, we have included IBM's JRE (Java Runtime Environment)
and their Jikes compiler.
- On the Macintosh, we have included Apple's MRJ (Macintosh Runtime for Java).
- On other platforms (such as Solaris and Linux) you still need to
install a JDK before you install Spin.
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.
- The files DebugServer.properties, General.properties, GetInfo.properties,
and ScriptOptions.properties are managed by Spin
you can modify them by choosing "Preferences" under the Edit menu.
- The file content-types.properties describes the MIME types understood by
Spin's internal web application server. You can edit this file if necessary.
- The file zatsql.properties specifies the databases and database drivers
available to the ZatSQL database components. You must edit this file if
you want to use Spin with another database.
See the Database section of this document
for more information.
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.
- The files zatapp.jar, zatload.jar, and zatservletdebug.jar contain Spin itself.
You may not make copies of these files in any form (except for backup purposes).
The files zat.jar and zatlib.jar contain files that are used by projects
built with Spin. You must deploy these files with any application, applet,
servlet, or component that you build using Spin.
The file zatservlet.jar must be deployed with any servlet built with Spin.
You do not need to deploy it with applications, applets, or components,
unless they contain servlet capsules.
The file jsdk.jar is Sun's Java Servlet SDK.
This file should be deployed with any servlets you build,
unless your servlet environment already includes this file
(and most of them do include it).
The file swingall.jar contains the Java Swing GUI widgets.
The file lax.jar contains LaunchAnywhere, which makes it possible
to run Spin by double clicking on it.
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;
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
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.
You can access the manuals online, in one of several ways:
- From the Spin "View" menu, using the "Spin Documentation" command.
- From any browser, by accessing the URL
- The Spin installation also generates an icon that will take you directly to
this Web page in your default browser.
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:
- Components that come with Spin, including the HTML beans, visual beans
like Text and Rect, and non-visual beans like Clock and SqlSelect.
- Components that come with Java, including AWT components like Button and Scrollbar.
- 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:
- For the JavaBeans that come with Spin, documentation is automatically
installed in the "docs" subdirectory of the Spin installation directory.
- For JDK documentation, Spin accesses this documentation from Sun's Web site.
- 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.
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,
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 is not especially difficult, there
are just lots of steps.
First, you must have installed the latest version of
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
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
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).
Spin comes preconfigured for the PointBase DBMS. To use Spin with other
databases, you will need to configure them in the zatsql.properties file.
Spin should work with any database that has JDBC drivers.
See the Spin Database documentation for more information.
- PointBase Server. Starts the PointBase DBMS. You can also have
PointBase start automatically when Spin starts by selecting the
PointBaseServerLoadsAtStart preference in the General tab of Spin
Preferences (in the Edit menu).
- PointBase Console. Used to manage your database, including setting
up database schema. See the PointBase documentation for more information.
- PointBase Documentation. In PDF format, so you will need the
Adobe Acrobat Reader.
6 March 2000 wm
Feedback to firstname.lastname@example.org