Zat Home
Documentation | Deployment

Deploying Spin™ Projects



This document discusses how to build and deploy projects in Spin, including compatibility information for various deployment environments. Note that due to the huge number of possible deployment environments, this information will never be complete, and is likely to change frequently. We encourage you to send us reports of environments in which you have successfully deployed Spin projects, and compatibility issues you have encountered.

Spin projects can be deployed in several ways: as components, servlets, applets, applications, and as distributed applications. Each kind of deployment has implications for you, the developer, as well as for the ultimate users of your project. In addition, each kind of deployment offers a large number of possible deployment environments, each with their own compatibility issues.

It is important to remember that Java is a very young language, and some of the technologies fundamental to Spin, including JavaBeans and servlets, are even younger and consequently evolving rapidly. Unfortunately, you need to be aware of these issues when you build a project in Spin.

Jar Files

Jar files are Java ARchive files. A single jar file can hold multiple Java classes (including multiple JavaBeans), along with other resources (images, icons, data, documentation, etc.) that are used by your project. Another advantage of jar files is that they are compressed (using the same compression algorithm as zip files). The Java Developer's Kit (JDK or MRJ) includes utilities for managing jar files.


When you use Spin, you take some actors (in the form of JavaBeans) along with some data, and connect them together using behaviors. The behaviors and data are stored in a capsule (.zac) file, which is an editable format. To actually use this capsule you need to save it as a JavaBean (in a jar file, which is an executable format), using the "Save As Jar" command in the File menu of any capsule editor (outline, toybox, or layout).

When you save a jar file, the name you give to the file is also used as the class name of your program. The class name is used to invoke the program. Note that you should always use the .jar extension for jar files.

The type of the capsule determines for what the saved jar file can be used. The "Edit Properties" command in the Capsule menu allows you to set the type of a capsule.

In the normal use of Spin, you will create capsules from other JavaBeans, saving these new capsules as JavaBeans themselves and using them (as actors) to build new capsules. You use a jar file (containing a JavaBean) as an actor by placing it in the "beans" subdirectory of the Spin installation directory.

Eventually, you will build a capsule that you want to use as a servlet, applet, or application. You set the type of this capsule as appropriate, and save it as a jar file. Finally, you need to deploy the resulting jar file. How to deploy the resulting jar files is the subject of the rest of this document.

Note that the JavaBeans you use to create a capsule (in the "beans" subdirectory) are not stored in either the capsule's .zac file, nor in the jar file you create when you do a "Save as Jar". It is up to you to collect all the JavaBeans you use in a project together when you deploy a project. The project window in Spin is a convenient place to keep track of all the JavaBeans and capsules (and other files) in a project.

Zat files

Your Spin installation directory contains several files that need to be deployed with your Spin projects.

The files zat.jar and zatlib.jar must be deployed with all Spin projects, whether they are deployed as applications, servlets, or applets. They must also be deployed as part of any project (whether built using Spin or some other JavaBean tool) that includes any JavaBean components built using Spin.

The file zatservlet.jar must be deployed with any servlet built with Spin. The file jsdk.jar is Sun's Java Servlet SDK. This file should be deployed with any servlets you build (whether or not built with Spin), unless your servlet environment already includes this file (and most of them do include it).


The easiest way to deploy a Spin project is as an application.

The first thing you need to do is gather up all the files used by your application. This includes the application's jar file, plus any jar files for JavaBeans used as actors by your application, plus the two Zat files zat.jar and zatlib.jar. For example, say you are building an application called myapp that contains the juggler JavaBean from Sun. Your application will require the following files: myapp.jar, juggler.jar, zat.jar, and zatlib.jar.

On platforms that support a command line interface (Windows and Unix), you can execute your application from the command line. For example, on Windows you can type:

java -classpath %CLASSPATH%;myapp.jar;juggler.jar;zat.jar;zatlib.jar myapp

On UNIX, using csh, the command would look like

java -classpath $CLASSPATH;myapp.jar;juggler.jar;zat.jar;zatlib.jar myapp

These commands assume that the JDK bin directory is in your PATH, and the JDK lib file is in your CLASSPATH. These commands invoke the myapp class in the file myapp.jar.

On Macintosh, you need to create an executable application using the JBindery tool, which comes with the MRJ SDK. JBindery can execute a Java application directly, or it can create an application that you can execute by double-clicking on its icon. Follow the directions that come with JBindery.


Typing in a long command to invoke a Spin application is inconvenient. Luckily, it is very easy to create an icon to invoke the application.

For example, on Windows, you can place the text of the command that invokes your application into a .bat file. You can then create Windows shortcuts to this .bat file. You can place a shortcut in the Start menu, or you can place a shortcut on the desktop or in a folder, and then double click on it to invoke the application. By editing the properties of the shortcut, you can change the icon to whatever you want.

On Macintosh, you can use JBindery to create an icon that you can double-click on to invoke your application.


If you are going to distribute your application to other people, you should create an installer that guides the user through the process of installing the necessary files. Such an installer can even install the necessary Java run time environment, if they do not already have it.

There are a number of install generator tools available for Java applications:

J'Express from DeNova.
InstallShield Java Edition from InstallShield.
DashO-Pro from PreEmptive Solutions.
InstallAnywhere from Zero G Software.
Install Toolkit for Java from IBM.

There is a free version of InstallAnywhere that comes with various Java development environments, including Visual Age, JBuilder, Parts for Java, CodeWarrior, Kawa, and Visual Cafe. If you go to the Apple MRJ web page, you can download InstallAnywhere Now! for the Macintosh.

Using an install generator tool makes deploying a Spin application as easy as deploying any regular application. Easier, actually, since you only need one version of your program to run on all platforms.


Spin itself generates applications that should run on any platform that supports Java 1.1 or higher. If you have any compatibility problems, please send them to

The most likely compatibility problems will come from JavaBean components that do not run on all platforms. For example, Quicktime JavaBeans require that Quicktime be installed on the target computer, so if you use the Quicktime beans in a Spin application, you need to make sure that the proper version of Quicktime is installed. In addition, Quicktime is only available on some platforms, so an application that uses Quicktime will only run on those platforms.


While it is normally possible to take the same Spin project and deploy it as either an application or an applet, this is not true of servlets. Servlets are unlike other Java applications in that they do not have their own user interface. Instead, a servlet runs on a web server, and interacts with the user remotely, using HTML and CGI to communicate with a web browser.

Another difference with servlets is that, unlike other kinds of capsules, when you save a servlet capsule as a jar file, that jar file does not hold any JavaBeans (but this should not really affect you or your servlets).

Web Servers and Servlet Engines

Java Servlets are supported by just about every web server in existence. Sun maintains a web page that lists all the web servers and server add-ons that support servlets. We have tested servlets built with Spin on the following web servers:

If you are able to run Spin servlets on other platforms, please let us know so we can add them to the list. Likewise, if you encounter problems running Spin servlets on any servlet engine, please send us email at so that we can resolve the issue as soon as possible.

How you deploy servlets built with Spin depends on the servlet engine you are using, but they are all similar.

Servlet Files and Classpath

As with applications and applets, the first step in deploying a Spin servlet is to gather up all the files used by your servlet. This includes four kinds of files:
  1. Servlet jar files. These are the files you create from your servlet capsules, using the "Save as Jar" command. Each servlet you create in Spin will have a separate .jar file.
  2. Zat jar files. This includes zat.jar, zatlib.jar, and zatservlet.jar.
  3. Jar files of JavaBeans used by your servlet. These are the jar files of any JavaBeans you use in your servlets. For example, most Spin servlets will use the HTML generating beans found in ZatHTML.jar.
  4. Other assets. This includes any other data used by your servlets.

These files will go into two different places:

Depending on your servlet engine, you might also need to configure each servlet. You can then invoke the servlet by typing it its URL.

For example, if you create a simple servlet called that uses the Spin HTML JavaBeans and save it in myservlet.jar, your servlet will need the following files: myservlet.jar, ZatHTML.jar, zat.jar, zatlib.jar, and zatservlet.jar. The file myservlet.jar will be put in your servlet engine's servlets directory, and the rest of the files will be put in some other directory and added to the servlet engine's CLASSPATH. With most servlet engines, you can invoke this servlet from a browser using the URL

where servername is the domain name of your server. With most servlet engines, you can also invoke the servlet using a <SERVLET> HTML tag.


Servlets generally have fewer compatibility issues than other Java programs, because they do not have a user interface nor use special media types or functions. If your Web server can run servlets, it is likely that it will run the Spin servlets that you create.

Some web servers have a bug that affects reading java resources from servlet .jar files. This causes problems running servlets that contain JavaBeans (which is true of all Spin servlets). Spin has a feature designed to work around this problem. When you deploy your servlet on the web server, set a servlet initialization parameter, JAR, to the Java file path of your servlet's .jar file. For example, on Windows this might be "JAR=/c:/webserver/servlets/myservlet.jar". When this initialization parameter is present, a Spin servlet will use the specified file to load the resources it needs.


Applets probably have the biggest deployment issues of any kind of project you can build with Spin. Because applets are downloaded into the user's browser before they are executed, your applets need to be compatible with every browser that might be used to access your web site. Unfortunately, this is not really possible. There are also security issues to contend with. Applets are untrusted code, so there are tight restrictions on what they are allowed to do.

In general, the only applets that are practical for general use on the Internet are fairly simple, and thus not particularly interesting. This situation is improving, however. Alternatively, applets are very practical in a controlled environment like an intranet inside a company, where you can ensure that everyone is using a certain browser, and where you can relax security for internal applets.

Again, to deploy an applet created by Spin, you need to gather up all the files in your project. This includes the jar file created when you saved your applet capsule as a jar file, plus any jar files containing JavaBeans you used in your applet (from the "beans" subdirectory), plus the Zat files zat.jar and zatlib.jar. You will place all these files together in a directory on your web server.

For example, if you create a simple applet that uses Sun's juggler bean, and save it in a jar file called myapplet.jar, you will need to place the files myapplet.jar, juggler.jar, zat.jar, and zatlib.jar into a directory on your server.

You can then access this applet from a web page using an <APPLET> tag.

<APPLET code="myapplet.class"
width="100" height="100">

This applet tag assumes that the applet is in the same directory as the HTML file containing the applet tag.


Older browsers do not support the "archive" parameter of the applet tag. These browsers cannot be used to access applets created by Spin, because they cannot deal with applets containing JavaBeans. One way to get around this problem is to combine all the jar files into a single jar file (using the JDK jar utility). This creates a single file that should run on most browsers in widespread use.

A bigger problem is that the browser needs to be compatible with Java 1.1. On the PC, Internet Explorer 4 (and higher) and Netscape 4.5 are compatible. On the Mac, Internet Explorer 4 (and higher) is Java 1.1 compatible. The latest Netscape, 4.5, is not Java 1.1 compatible (on Mac), and so will not run applets containing JavaBeans. Word is that Netscape 5 should be compatible.

Some versions of Internet Explorer have problems accessing resources in jar files. For example, if you use Sun's juggler bean in an applet, it might fail because it cannot access the embedded images. You can work around this problem by using a standard zip utility to extract the images from the jar file. Then upload these images onto your server, placing them in their full relative path (for the juggler, starting with "sunw").

A workaround for compatibility issues on some platforms is to install the free "java plug in" from Sun on your browser.


The actions an applet is allowed to perform depend on many factors: which browser you are using, what level of security you have enabled in your browser, whether or not the applet is digitally signed, where the applet is downloaded from, and so on. The issue of applet security is way beyond the scope of this document.

In general, applets are only allowed to access resources from the server from which they were downloaded. Your applet will fail if it tries to access resources on the local machine (running the browser) or on other web servers. For example, the StockGraph demo (included with Spin) will not run under normal applet security, because it accesses resources on another server (the stock info).

Here is a link for more information on applet limitations and signed applets.

You can usually test out applets by loading them from your local machine, however, there is a bug in some versions of Internet Explorer that causes locally accessed applets to generate a security exception. If you upload the same applet to a server and access it over the network, it will run fine (assuming it has no other security problems).

Distributed Applications

A distributed application is built up from regular applications, servlets and applets. These parts can communicate in many different ways: In general, for the fancier kinds of communication it is better to use some JavaBeans that hide the low-level details of the communication from you. Right now, Spin has support for CGI, HTML, and remote databases. You can also find JavaBeans that support other forms of distributed communication. More and better support for distributed applications will be built into Spin in the future.

7 June 1999 — wm