|
|
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.
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.
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).
Applications
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 classes.zip 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.
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.
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.
Servlets
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).
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 bugs@zat.com 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.
.jar file.
These files will go into two different places:
All of these .jar files must be added explicitly to your servlet
engine's CLASSPATH so that they can be found at runtime.
Refer to your servlet engine documentation for instruction on how to
set its CLASSPATH variable.
Note that it is not sufficient to add just the directory containing the
.jar files to the CLASSPATH, every .jar
file must be individually added to the CLASSPATH, including the Zat
files zat.jar, zatlib.jar, and zatservlet.jar, and any .jar
files containing JavaBeans used by your servlet (such as ZatHTML.jar).
Your servlet jar files, which you placed in your servlet engine's servlets directory,
do not need to be placed in the CLASSPATH since they will be invoked directly.
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
http://servername/servlet/myservletwhere servername is the domain name of your server. With most servlet engines, you can also invoke the servlet using a <SERVLET> HTML tag.
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
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"
archive="myapplet.jar,juggler.jar,zat.jar,zatlib.jar"
width="100" height="100">
</APPLET>
This applet tag assumes that the applet is in the same directory as the HTML file containing the applet tag.
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.
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: