Installing and Configuring ZimWeb
Installation
Here are some additional details about installing ZimWeb.
The ZimWeb package
ZimWeb is packaged as a WAR (Web Application Archive) file containing the following files:
| Package | Contents |
|---|---|
| example/index.htm | Home page for the ZimWeb Example Application. |
| WEB-INF/example/template/*.htm | Page templates for the ZimWeb Example Application. |
| WEB-INF/example/xslt/*.xsl | XSLT style sheets for the ZimWeb Example Application. |
| WEB-INF/web.xml/ | Configuration for the ZII servlets. |
| WEB-INF/lib/avalon-framework-xxx.jar | Apache Avalon Framework (required by Apache FOP). |
| WEB-INF/lib/batik-xxx.jar | Apache Batik SVG processor (required by Apache FOP). |
| WEB-INF/lib/fop-xxx.jar | Apache FOP XSL-FO processor. |
| WEB-INF/lib/jimi-xxx.jar | Sun JIMI (required by Apache FOP). |
| WEB-INF/lib/jfor-xxx.jar | JFOR XSL-FO processor for RTF. |
| WEB-INF/lib/avalon-framework-xxx.jar | Apache Avalon Framework (required by Apache FOP). |
| WEB-INF/lib/zii.jar | ZimWeb itself. |
| WEB-INF/lib/jaxp/xalan-xxx.jar | Apache Xalan XSLT processor (in case this is not part of your Java or servlet engine environment). |
| WEB-INF/lib/jaxp/xercesImpl-xxx.jar | Apache Xerces XML parser (in case this is not part of your Java or servlet engine environment). |
| WEB-INF/lib/jaxp/xml-apis-xxx.jar | XML APIs for XML parsing and XSLT processing from Apache Xalan-Java (in case this is not part of your Java or servlet engine environment). |
The ZimWeb file zii.jar contains classes in the following Java packages:
| File | Description |
|---|---|
| zim.CGIServer | The original ZimCGI, with a few modifications |
| zim.jdbc | Zim JDBC Driver |
| biz.zim.zii | The main ZimWeb classes |
| biz.zim.util | Utility classes for ZimWeb |
There are two servlets in ZimWeb which you can invoke:
| Servlet | Description |
|---|---|
| biz.zim.zii.ZIIServlet | The ZimWeb itself. This is the servlet that you invoke to service a request to a Zim web application instead of the zimcgic.exe (or whatever) of the ZimCGI. You will probably want to alias to something shorter. The ZimWeb sample configuration file web.xml for Tomcat shortens it to ZII, so if, say, you installed it with Tomcat‘s default parameters (servicing port number 8080), you would invoke it with a URL like http://:8080/ZII/servlet/ZII. |
| biz.zim.zii.ZIIAdminServlet | The ZimWeb Administration servlet allows you to administer ZimWeb. including checking its configuration parameters, starting and stopping Zim Server agent connections, and checking and clearing the XSLT style sheet cache. Read more about ZimWeb administration. N.B. In a production environment, you want to secure access to this servlet – you can shut down your Zim web application with a single click! To find out more information on this topic please read below or check out your Java Servlet Engine. |
The ZimWeb jar file also contains the ZimCGI Server – equivalent to the zimcgis.jar file. You may wish to use the zii.jar for both purposes to avoid problems with multiple versions on your Java CLASSPATH.
Example: Installing the ZimWeb on Tomcat V4.1.x
Before installing ZimWeb . make sure you have a working Tomcat installation, consisting of, say, Java 1.4.x plus Tomcat V4.1.x LE. N.B. You choose a Tomcat LE version with Java 1.4.x because Java 1.4 includes XML processing facilities which would otherwise be duplicated in Tomcat.
One way of installing the ZII on Tomcat V4.1.x is as follows:
- Place the ZimWeb WAR package file ZII.war in the directory [TOMCAT_ROOT]/webapps.
- Remove any directory [TOMCAT_ROOT]/webapps/ZII if it already exists e.g. if you have installed a previous version of ZimWeb .
- Start Tomcat. This automatically unpacks the contents of the file ZII.war into the directory [TOMCAT_ROOT]/webapps/ZII. It most likely won’t connect successfully to any Zim database because the ZimWeb configuration file requires adjustment.
- Stop Tomcat.
- Adjust the ZimWeb configuration file [TOMCAT_ROOT]/webapps/ZII/web.xml as appropriate. In particular, you should ensure that the config-file and log-file parameters are set correctly. Note also that it secures the ZimWeb Administration servlet so that it can only be accessed by users in the role ZimWeb .dmin – see the next step for how to add such a user.
- Adjust the Tomcat configuration file [TOMCAT_ROOT]/conf/tomcat-users.xml to add a user in the role ziiadmin that can administer ZimWeb e.g. to add a user ZimWeb .dmin with password ZimWeb you could do this by adding lines such as these into it:
…
…
…
- Adjust the Tomcat configuration file [TOMCAT_ROOT]/conf/server.xml so that the ZimWeb application is logged separately from other applications into [TOMCAT_ROOT]/logs/localhost_ZII_log..txt. You can do this by adding the following context:
…
…
reloadable=”true” crossContext=”true”>
prefix=”localhost_ZimWeb_log.” suffix=”.txt”
timestamp=”true”/>
…
…
- Important! You must ensure that ZimWeb‘s enviroment includes XML parsing and XSLT facilities, and that there are no conflicts amongst the XML processing facilities which may be supplied with your Java and Tomcat environments and ZimWeb. For example:
- If you are running a Tomcat LE version using Java 1.4 or higher, then the Java environment already includes XML parsing and XSLT facilities, and no action is required.
- If you are running Tomcat non-LE version using a Java version prior to 1.4, then you will have to copy the files supplied with ZimWeb in the WEB-INF/lib/jaxp directory (xalan-xxx.jar, xercesImpl-xxx.jar and xml-apis-xxx.jar) into the [TOMCAT_ROOT]/common/endorsed directory, replacing any versions of those files which came with you version of Tomcat.
- Restart Tomcat. It will automatically start the Zim database connections if it is configured to do so.
The above should get you started. You will probably want to configure Tomcat further – particularly by adjusting the file [TOMCAT_ROOT]/conf/server.xml – before installing into a production environment.
Note: Make sure that you do not have the zimcgis.jarfile from the ZimCGI in your Java CLASSPATH, otherwise they may interfere with one another.
Tomcat can be configured to run both standalone, or in conjunction with other web servers like Apache.