Documentation | Installation Guide

This manual covers installation issues on various platforms.

Table of Contents

• Introduction
• Installation Files and Directories
• Invoking Spin
• Documentation
• Installing Components
• Reinstalling and Upgrading Spin
• Database

Introduction

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.

• 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

asset

Where any images, sounds, animations, and other asset files used by the example programs are stored.

beans

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.

behaviors

Where all user-defined behaviors are stored.

docs

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.

examples

Where client-side example programs are stored. This is a convention only — you can put Spin projects and capsules anywhere.

icons

Spin icons

jikes

The Jikes Java compiler from IBM. Installed on Windows only.

jre

The Java Runtime Environment from IBM. This directory only exists if you used the Windows Spin installer that includes Java.

pointbase

The PointBase DBMS (DataBase Management System). Used to develop database applications with Spin.

public_html

Where the Spin debug web server finds html files. The location of this directory can be changed using a Spin preference.

servlets

Where server-side example programs are stored. This is a convention only — you can put Spin projects and capsules anywhere.

sources

Spin uses some Java code whose source is freely available. We include that source code here for you.

temp

Spin uses this directory when "grinding beans" to hold intermediate results.

UninstallerData

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 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.

• 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.

Invoking Spin

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

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.

Documentation

Spin Manuals

• From the Spin "View" menu, using the "Spin Documentation" command.
• From any browser, by accessing the URL http://www.zat.com/documentation.html.
• The Spin installation also generates an icon that will take you directly to this Web page in your default browser.

GetObjectInfo Documentation

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

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 http://java.sun.com/products/jdk/1.1/docs.html. 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

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

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

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.

Database

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:

• 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 bugs@zat.com