Zat Home
Documentation | Servlets

Building Servlets with Spin™

Table of Contents


A servlet is a program that runs on a server, typically a Web server. Unlike most programs built with Spin, a servlet does not have its own GUI (Graphical User Interface). Instead a servlet typically uses a Web browser (like Netscape Communicator or Microsoft Internet Explorer) for its GUI.

A servlet responds to an GET or POST request sent from a browser, and responds with data such as HTML or an image. GET and POST are defined by the HTTP (HyperText Transfer Protocol) specification.

Spin incorporates the following features for building servlets:

Running a Simple Servlet

A simple servlet example, hello.zac, is provided here. Save it in your servlets subdirectory, and open it in Spin.

The ActionGroup ServletGet handles the servlet response. This behavior is also found in the Insert > User Behavior menu.

Execute the servlet from your browser by calling Spin's built-in debug Web server with the URL http://localhost/servlet/hello

This assumes that the Web server has been turned on, and is set to listen on port 80. See the section on DebugServer Preferences.

The servlet will be compiled automatically and executed when Spin's web server receives the request for it. The simple output should appear in your browser. Note that to respond to a Get request two things are necessary:

  1. Set the content type to be returned (setContent behavior)
  2. Print your HTML document to the output writer (sendDocument behavior)

Specifying the URL http://localhost from your browser while Spin is running will display the HTTP request you just made along with a list of the servlet files currently open in Spin that can potentially be executed. Execute them by clicking on their links.

Creating a Java Servlet

To create a new Java Servlet, you must create a special kind of capsule, called a Java Servlet. First, create an empty Capsule by choosing File >New Capsule from the menu. Now edit its properties by choosing Capsule > Edit Properties from the menu. The following dialog is displayed. Choose Java Servlet from the Type Tab, and close the dialog.

DebugServer Preferences

The Web server built into Spin has a number of preferences. These are accessed by choosing Edit > Preferences and then selecting the DebugServer tab.


The built-in web server allows you to test the servlet Post request by allowing you to enter named parameters that are automatically fed to the servlet. This preference allows you to set the maximum number of parameters allowed.


Spin's built-in web server is configured by default to listen on port 80, which is the default port for Web servers. If you already have a Web server on your machine, you will need to switch this to another value. A typical alternate value is port 90 (except on UNIX, where port 8080 is typically used). The only restriction on the port number is that you must be careful to not use a port already in use by some other protocol.

If the server port number is 80, then you can access the Spin Web server from a browser using the URL (Universal Resource Locator)

If you change the server port, then you will need to specify the port number to access the Spin Web server from a browser. The port number is specified after the host name, separated by a colon. For example, if you change the port number to 90, use the URL


Specifies how the Spin Web server knows if a URL is a request for a servlet. The default value of this preference is "servlet", which means that URL's of the form
where servletname is the name of the servlet, will be interpreted as servlets.


Allows you to turn Spin's built-in web server on or off. By default, the Web server is turned off, and must be turned on to build and test servlets.


The property URLOrDirectoryForNonServletRequests determines how Spin resolves URL requests that are not active servlets. If that property is a directory name, then Spin will satisfy requests from files in that directory. If that property is a URL that begins with "http://", then spin will satisfy requests by appending the request to that URL and call the appropriate server for a response.


Save your servlet as a .jar file. You can now deploy it in your web server provided all the bean .jar files (at minimum ZatHTML.jar) and zat.jar, zatlib.jar, and zatservlet.jar are in your server's classpath. Note that when you save the servlet .jar file, a class is generated of the same name as the file name (without the .jar), and that is the class that is the HttpServlet subclass which your web server will need to execute.

Not all web servers are created equal when deploying Java servlets. In particular your web server needs to be able to cope with servlets packaged in Java archive files, and also requires the Java classloader to be able to load resources from those files.

Presently we have approved Sun's Java Web Server, and vqSoft's vqServer for use with servlets generated by Spin.


Creating HTML with Spin

Zat.html JavaBeans

Zat.html is a package of JavaBeans created for Spin that can help you develop dynamic programmable html content for use in a servlet environment. The entire range of HTML3.2 is available in this library of easy-to-customize JavaBeans. To use them, simply drop the file ZatHTML.jar into your beans directory before you launch Spin (the regular Spin installer does this for you).


Document vs. Template

Creating dynamic html with Spin can be done in one of two basic modes: template and document.

In template mode, Spin uses a regular HTML document (created with any HTML authoring tool) that contains one or more special ZAT HTML tags. Inside Spin, you insert an HTMLTemplate component into your project, and set its Path property to the filename of the HTML file. Spin replaces the special ZAT HTML tags in the document with dynamic content defined by HTMLMacro components.

In document mode, the entire HTML document is defined in Spin. The root of the HTML document is an HTMLDocument component. HTMLDocument outputs an entire html document (HTML, HEAD, TITLE, BODY, etc.), and can be used for small or simple documents with a large amount of dynamic content.

Here is the editor for HTMLDocument:

The Outline Hierarchy in Spin

The outline hierarchy in Spin simulates the nested nature of html. Each JavaBean in the package is either a container element (a potential parent) or an end node. For example, HTMLTextStyle is a logical parent for HTMLText while HTMLHorizontalRule is not a container, and cannot be the parent of other beans in the package.

The outline view below is an example of a typical HTMLDocument hierarchy in Spin:

Templates and Macros

HTMLTemplate is a convenient way to edit static html in your preferred editor, then import it into a Spin servlet. The HTMLTemplate JavaBean can read and parse any HTML text file. It detects the presence of the special tag <ZAT> and replaces them with dynamic content. The HTMLMacro JavaBean is a named parent which inserts its content into the final output where you specify. The <ZAT>/Macro pairs can be named or can simply occur in their natural order.

For example, anywhere <ZAT NAME="Macro_One"> is found in your original html file is replaced by the dynamic contents of the HTMLMacro named Macro_One in your Spin Servlet Capsule:

Important Note: The visible 'name' of the HTMLMacro in the outline is not the same as the NAME property of the JavaBean.

Also, HTML Template may be used to represent a snippet of HTML code, and nested inside any other parent bean in the zat.html hierarchy.

Using Zat.html

Generating HTML Output

HTML output (whether an entire document or just a snippet) is generated by sending the print(PrintWriter) message to any of the beans in zat.html. The appropriate PrintWriter can be obtained from the Spin Servlet Capsule by way of the method PrintWriter getWriter(). Any children of a zat.html JavaBean which receives the print message will also print, automatically. The output will be generated from top to bottom and nesting will occur just as it is displayed in the Spin Outline view.

Subgroups in zat.hmtl

Several of the JavaBeans in zat.html make sense only within a limited context. HTMLListItem, for example, will only generate proper html if it is the direct child of an HTMLList bean. This is due to the very nature of html itself. Although it is legal to have a <LI> tag without a <OL> or <UL>, it will not be displayed properly in the browser. Here is a diagram of the subgroups in zat.html:

TagEnabled and TreeEnabled

Every JavaBean in the zat.html package contains two important properties: TagEnabled and TreeEnabled. Both of these values are true, by default. They are used to control the flow of output within dynamic html. Your application logic (represented in Spin by behaviors, most commonly actions) can decide to enable or disable portions of the html hierarchy by setting these values. TagEnabled mutes the output of the bean in question when set to false, but allows its children to output normally. TreeEnabled when set to false effectively 'shuts off' the output of all children of this bean, and continues the output with the next sibling down the list. If you want to turn both the current bean and its children off, you should set both TagEnabled and TreeEnabled to false.


HTML Repeater is a unique HTML bean in that it outputs no HTML by itself, but is used as a flow control device. The children of an HTMLRepeater are simply output a number of times equal to the value of the repetitions property of HTMLRepeater, which can be modified at runtime to create dynamic tables, database lookups, etc.

Container Elements and End Nodes

Although each JavaBean in zat.html can be nested within any other in a Spin capsule, the nature of the HTML tag that each bean represents determines whether it is an appropriate container. Any container element usually generates start and end tags which 'contain' the html generated by its children. For example, HTMLAnchor would have as a child the content of the link to be created, whether it be an HTMLImage bean, HTMLText bean, or any other.

The following are end nodes and not proper containers in zat.html:

More Information

For more precise information on the JavaBeans in zat.html, consult the Javadoc files distributed with ZatHTML.jar. This documentation is installed by the regular Spin installer.


Tag Index for zat.html

Below is a list of the HTML3.2 tags supported at this time by zat.html. To the right is the name of the JavaBean which outputs the tag.
Tag   zat.html JavaBean    Description
<A>  HTMLAnchor hyperlink
<B>  HTMLTextStyle bold font
<BIG>  HTMLTextStyle use big font
<BLOCKQUOTE>  HTMLBlock indent text
<BODY>  HTMLDocument document body
<BR>  HTMLLineBreak line break
<CODE>  HTMLTextStyle font for program listings
<CITE>  HTMLTextStyle font for citations
<DD>  HTMLListItem definition list definition
<DFN>  HTMLTextStyle defining instance font
<DIV>  HTMLBlock align left, center, or right
<DL>  HTMLList definition list
<DT>  HTMLListItem definition list term
<EM>  HTMLTextStyle emphasis font
<FONT>  HTMLFontStyle font face and size
<FORM>  HTMLForm input form
<H1>-<H6>  HTMLHeading heading, levels 1 through 6
<HEAD>  HTMLDocument document head
<HR>  HTMLHorizontalRule horizontal rule
<HTML>  HTMLDocument root of html document
<I>  HTMLTextStyle italic font
<IMG>  HTMLImage insert image
<INPUT>  HTMLFormInput element in input form
<KBD>  HTMLTextStyle font for keyboard input
<LI>  HTMLListItem list item
<OL>  HTMLList ordered (numbered) list
<OPTION>  HTMLFormSelectOpt element in select input
<P>  HTMLParagraph paragraph
<SAMP>  HTMLTextStyle font for sample output from program
<SELECT>  HTMLFormSelect select from options input
<SMALL>  HTMLTextStyle use small font
<STRIKE>  HTMLTextStyle strike-through font
<STRONG>  HTMLTextStyle font for strong emphasis
<SUB>  HTMLTextStyle subscript font
<SUP>  HTMLTextStyle superscript font
<TABLE>  HTMLTable table
<TD>  HTMLTableCell table data cell
<TEXTAREA>  HTMLFormTextArea text input
<TH>  HTMLTableCell table header
<TITLE>  HTMLDocument document title
<TR>  HTMLTableRow table row
<TT>  HTMLTextStyle teletype (monospaced) font
<U>  HTMLTextStyle underlined font
<UL>  HTMLList unordered (bullet) list
<VAR>  HTMLTextStyle font for variables or output from commands


7 March 2000 — bf, pjg, wm

Feedback to