Web Applications Accessing Zim:X – Page 2

ZimWeb Commands

The output from the Zim Server agent is sent to ZimWeb and then to the client (web browser, cellphone, tablet, etc.). However, there are various commands that can be used to control how the Zim application output is processed, and how ZimWeb behaves.

ZimWeb expects that the Zim application will output a series of ZimWeb commands (one per line), a blank line, and then the actual content.

To send HTML to a web browser, the beginning of the application’s output should be:

content-type:text/html

etc…

N.B. The blank line between the content-type: line and the start of the content is very important!

Commands are not case sensitive. In case you are wondering about the content-type line, it is not send directly to the web browser.

Commands Organized by Function Type

Content processing
`content-type:`	Sets the response content type to . You do not need to set this if you are applying an XSLT stylesheet with the `apply-xslt:` command and the ZimWeb is configured to use the output type specified in the stylesheet’s output method. If this is specified, and a stylesheet is being applied, then the content type specified will override the stylesheet’s output method. If the ZimWeb cannot determine the content type, it will assume it is `text/html`, except if the client requests no styling (parameter `STYLE=none`), then, if there is no `content-type:` command, the content will be assumed to be XML (mime type `text/xml`), since you can only style XML. If that all sounds rather complicated, it’s just trying to express explicitly some fairly reasonable and benign assumptions.
`apply-xslt:`	Apply XSLT stylesheet to the Zim agent output. The parameter is a file path relative to the base path of the ZII application. If you have installed the ZimWeb in the manner described in the installation instructions then specifying the as `/styles/cool.xsl` will refer to the file `[TOMCAT_ROOT]/zii/styles/cool.xsl`. The parameter can be overridden by the input parameter `STYLE`. The ZimWeb automatically compiles and caches XSLT stylesheets in memory for maximum performance. N.B. The ZII does not accept a URI for the stylesheet as running a stylesheet not under your control could be a security hazard.
`apply-page-template:`	Apply the page template to the Zim agent output. The parameter is a file path relative to the base path of the ZimWeb application, just like the parameter above. The parameter can be overridden by the input parameter `PAGETEMPLATE`. The ZimWeb automatically compiles and caches page templates in memory for maximum performance. Read more about using page templates. N.B. ZimWeb does not accept a URI for the form template since this could be a security hazard.
`apply-xslfo:`	Treat the Zim agent output, or the result of the other content processing (typically XSLT, though it could be a page template), as XSL Formatting Objects and render it with the specifed . The two rendering options currently available are PDF (Adobe Portable Document Format), for which you would specify `apply-xslfo:pdf`, or alternatively RTF (Rich Text Format), for which you would specify `apply-xslfo:rtf`. Note that rendering to PDF is much more accurate than rendering to RTF.
HTTP session parameter management
`set-session-parm:=`	Sets the session parameter to the value . If the parameter already exisits, then its value is changed to . Once set, the parameter will be available for inclusion in the `TEMPLATE` parameter. Session parameters remain set until they are cleared, or the session times out or is invalidated. Session parameters are not sent to the client – they are managed by the ZII servlet. N.B. Cookies should be enabled on the client’s browser in order that http session parameters function correctly. If the same parameter exists in several places then the form parameters have priority over the session parameters, and these have priority over the cookie parameters.
`clear-session-parm:`	Clears the session parameter .
`invalidate-session`	Terminates the client session and starts a new one. This will cause all session parameters to be discarded.
`session-timeout:`	Sets the session timeout to seconds. If not specified, the session timeout defaults to the value specified in the Configuring ZimWeb . N.B. It only changes the timeout for this session, not any other session, and it does not change the default session timeout.
Cookie parameter management
`set-cookie-parm:=`	Sets the cookie parameter to the value . If the parameter already exisits, then its value is changed to . Once set, the parameter will be available for inclusion in the `TEMPLATE` parameter. Cookie parameters remain set until they are cleared, or the cookie reaches its expiry time. To work, using cookie parameters requires that the client has cookies enabled. N.B. Cookies should be enabled on the client’s browser in order that cookie parameters function correctly. If the same parameter exists in several places then the form parameters have priority over the session parameters, and these have priority over the cookie parameters.
`clear-cookie-parm:`	Clears the cookie parameter . N.B. This will not clear the `JSESSIONID` cookie which is required for session management.
`clear-all-cookies`	Clears all the cookies set by the ZimWeb . N.B. This will not clear the `JSESSIONID` cookie which is required for session management.
`cookie-timeout:`	Sets the cookie timeout to seconds, as opposed to the default cookie timeout, for cookies set after it in the ZimWeb commands. A negative timeout indicates that the cookie will expire when the user exits the client. However, I would suggest you use a session parameter instead in that case. N.B. It does not change the default cookie timeout.
Persistent Zim session management
`start-zim-session`	Start a persistent Zim session. Key points to note about this are:- This is the Zim application requesting that the Zim session is to persist, not a request by the client. If the persistent Zim session is being managed by a `SESSIONID` parameter in the form parameters then the Zim procedure must include the `SESSIONID` parameter in its `TEMPLATE` in order that it can continue using that Zim session. Unlike the ZimCGI, all Zim database agent requests have a `SESSIONID`; but of course Zim sessions that are not to persist are ended at the end of the request in which they were started.
`end-zim-session`	Ends the current persistent Zim session.
`cancel-zim-session`	Ends the current persistent Zim session without sending any response to client.
Status and error codes
`set-status:`	Set an HTTP status code (without a message – sending a message with a status code is depricated) to the client.
`send-error:[:]`	Send an HTTP error code, with or without a message, to the client.
Authentication
`request-authentication:`	Send a BASIC authentication request for a given realm to the client.
Miscellaneous
`redirect:`	Redirect the client to a new URL.
`set-cache-time:`	Set the caching time for a response in seconds (normally the responses indicate that they cannot be cached).
`set-header:=`	Set a string HTTP header to a given value.
`set-int-header:=`	Set an integer HTTP header to a given value.
`set-date-header:=`	Set a date HTTP header to a given value. N.B. Dates are in milliseconds since the epoch (midnight on January 1, 1970).

ZimWeb Features

ZimWeb requires a TEMPLATE parameter. It is not optional (see Parameter Template can be Specified for this Procedure).

Ability to Handle POST and GET Requests

ZimWeb can accept parameters via either a POST request or a GET request (with the parameters in the URL, which means you can bookmark a ZimWeb request or add a hyperlink).

Debug Information

If you supply the parameter DEBUG in the request, you can see all sorts of useful details about the parameters, the http headers, etc., which can be very useful for debugging.

Note: Since exposing the debugging information to any client may pose a security hazard, the ability to debug a request can be enabled and disabled by the application administrator.

HTTP Session and Cookie Parameter Management

Note: When we refer to a client session, we are referring to the HTTP session, not the Zim Database Agent session.

ZimWeb allows you to control and access client session and cookie parameters.

For example, your ZimWeb application could set the client session parameter PASSWORD to indicate a password that the user had supplied when they logged in. From that point, the parameter PASSWORD, if referenced in the TEMPLATE, would be supplied with that value, until the user exited their browser, the session timed out (which the application can control), or your application cleared the parameter or invalidated the session (i.e. they logged out from your Zim application).

Client session parameters do not cause the Zim Database Agent session to remain open, so your Zim Dabase Agents remain available between processing client requests.

Also, client session parameters are managed by ZimWeb and are not sent to the browser, which can be good from a security standpoint.

Similarly, your application could set a cookie parameter USERNAME to the user’s name if, say, they check a “Remember me” box. Your application will then receive the USERNAME parameter, which can be a reference in the TEMPLATE, until the cookie expires (which the application can control) or the parameter is cleared.

In addition, ZimWeb allows you to specify that particular parameters which only comes from the HTTP session or cookies, by prefixing their names with the session or cookie respectively.

Access to Key Information About the Request

ZimWeb exposes key information about the request as parameters which can be included in your TEMPLATE, these include:

The PathInfo of the request is placed in the PATHINFO parameter. For example, say the ZimWeb servlet (ZII) is at the URL http:www.mycorp.com/ZII/servlet/ZII – if it receives a request for a URL relative to that e.g. http:www.mycorp.com/ZII/servlet/ZII/one/two, then the PATHINFO parameter would be set to /one/two.
The URL of the request entered by the client (including any Pathinfo, but excluding any parameters) is placed in the REQUESTURL parameter.
If the client HTTP session is being tracked through a cookie (which it must be for HTTP sessions to function correctly), the parameter SESSIONFROMCOOKIE is set to 1, otherwise 0.

Support for Client Authentication by Different methods

ZimWeb provides support for client authentication in various different ways:

If the client has been authenticated by the web server or servlet engine, their user name is placed in the AUTHUSERNAME parameter, and the authentication method (usually BASIC) is placed in the AUTHTYPE parameter.
The Zim application can force the client to authenticate itself using the request-authentication: command, and discover the (unauthenticated) user name and password of the client through the CLIENTUSERNAME and CLIENTPASSWORD parameters.
The Zim application can record the client’s authentication status in HTTP session parameters.

Control Over the Response

ZimWeb gives the Zim application control over the response sent back to the client, including the ability to:

Redirect the client to a particular URL.
Set how long the response can be cached by the client.
Set the HTTP status or error code and message.
Set arbitrary HTTP headers.

Improved Zim Session Control

ZimWeb includes options to improve the security of, and to simplify the use of, persistent Zim sessions:

Improved security by preventing clients from starting sessions when the Zim application is not expecting this – this could be used to deny service by committing all the Zim Database Agents.
Zim sessions can be placed under the exclusive control of the Zim application through the start-zim-session, end-zim-session and cancel-zim-session commands, coupled with disabling the input parameters previously used to control Zim sessions.
New or rewritten applications can manage Zim sessions through the HTTP session, eliminating the need to pass the SESSIONID parameter back and forth.

XML and XSLT Support

If your Zim application generates XML output, then it can request that an XSLT style sheet is applied to that XML to generate what is sent to the client (web browser, cellphone, etc.).

Also, the web request can indicate that a particular style sheet is required, overriding the style sheet specified by the Zim application. It can even request that no style sheet is used, returning instead the raw XML.

XSLT stylesheets are automatically compiled and cached in memory for maximum performance. The web-based administration tool allows you to see which XSLT stylesheets are cached, and also enables you to clear the cache, forcing the stylesheets to be reloaded, which is useful if you have changed the stylesheets.

There is no upper limit on the XSLT stylesheet cache size – if you run out of memory through caching stylesheets then you haven’t got enough memory to run your application efficiently.

Page Template Support

Some pages, particularly those designed by graphic artists etc., may not be convenient to turn into XSLT stylesheets (see XML and XSLT support).

ZimWeb includes page template support. A page template is just a regular page (HTML or XML), with parameter placeholders to indicate where each parameter to be supplied by the Zim application is to be placed. This template can be designed easily with your normal web page design tool.

The Zim application can then supply the parameters in an XML format. These parameters are combined with the template, with the result page being delivered to the client.

Just as with the XSLT processing, the templates are compiled into memory for maximum performance, and the request can specify an alternative, or even no page template.

XSL-FO Support

ZimWeb includes XSL-FO support – this allows the Zim application to render XSL-FO (Formatting Objects) – usually the result of XSLT processing, though it can be from a page template or even the unprocessed Zim agent output – into Adobe Portable Document Format (PDF) or Rich Text Format (RTF), so the application can deliver typeset output directly to the client’s browser.

Parameter Template can be Specified for the Procedure

When specifying which procedures can be run for a given connection, you can also specify the parameter template, eliminating the need the supply a TEMPLATE parameter with the request.

Improved Zim Session Control

The Zim application can directly control the termination of a Zim session – i.e. whether a Zim Database Agent is dedicated to a particular client, or is released when a request has been processed. This is very useful in preventing “denial-of-service” to the Zim web application by holding open every available Zim database agent.

Of course, the ZII’s HTTP Session and Cookie Parameter Management eliminates much of the need to hold open the Zim session.

Ability to Start ZimWeb Automatically When Java Servlet Engine Starts

By setting “load-on-startup” for the ZimWeb servlet configuration (the file web.xml if you are using Tomcat), ZimWeb will automatically start, and create all the Zim Database Agent sessions, when the Java Servlet Engine starts.

Note: If the Zim Server is not available, the ZimWeb will start anyway, and you can start the Zim Database Agent sessions when Zim Server does become available with the web-based administration tool.

Administration Tools

ZimWeb has a web-based administration tool, which enables you to:

Monitor, start and stop the Zim Database Agent sessions e.g. if you want to prevent access to the Zim application for maintenance purposes.
Enable or disable client request debugging.
See the value of the startup parameters.
Monitor and clear the XSLT style sheet and page template caches (e.g. if you update your style sheets or page templates, they will not be read if the style sheet or page template is already cached in memory.)

In addition, ZimWeb includes a utility which enables you to perform these functions from the command line or automatically in scripts, scheduled tasks, etc.

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.

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.

creating secure zim web applications

fbarbosafbarbosa182003-01-27T14:37:00Z2003-01-27T14:45:00Z12721552ZIM Technologies12319059.3821

Creating Secure ZimWeb Applications

Some key guidelines for creating secure ZimWeb applications include:-

Secure access to the ZimWeb Administration servlet so that unpriviledged users cannot access it. The installation instructions for Tomcat (See Installation) show how to reserve it for a given user name and password.
Ensure that the client DEBUG facility is disabled by default by setting the allow-debug configuration option to no.
Specify a TEMPLATE in the security configuration for all procedures – this is described in the configuration file extensions.
Avoid or restrict using Zim sessions if at all possible, as they are openings to a denial of service by committing all the Zim database agents:
- Use http session variables to preserve state information instead – see parameter sources for more details about this.
- Use the most secure setting possible for the zim-session-security configuration option– preferably disable persistent Zim sessions if they are not requred, or track Zim sessions in the http session. In addition, existing unmodified ZimCGI applications can also have their security improved.
Record the authentication of a user in an http session parameter e.g. session.AuthenticatedUser, which is present in all procedure templates and checked by all procedures. The initial authentication can be performed by the web server or the Zim application.
Place XSLT stylesheets and templates in a secure location that cannot be accessed directly by clients. A suitable location is under the WEB-INF directory of the application, as demonstrated by the ZimWeb example application.
Be careful about what XML information is output by the application – remember that the client can specify style=none in any request to see the raw, unstyled XML data.