XML URIs

The various XML technologies incorporated into ZimWeb may require references from one source to another (e.g. one XSLT stylesheet referencing another, or a reference to an external image in XSL-FO).

The following explains precisely how references to other sources (URIs) are interpreted in different circumstances.

URIs in XML generated by the Zim database agent

If there is a relative URI in the XML generated by the Zim database agent – e.g. a reference to a DTD (document type definition) – then this is interpreted as relative to a file zii.xml (which does not have to exist) in the base path of the ZimWeb application.

(e.g. If you have installed ZimWeb in the manner described in the installation instructions then specifying that a DTD is at path dtd/mydtd.dtd will refer to the file [TOMCAT_ROOT]/ZII/dtd/mydtd.dtd.)

URIs in XSLT stylesheets

If there is a relative URI in an XSLT stylesheet – (e.g. a reference to another stylesheet or document) – then this is interpreted as relative to that stylesheet. (e.g. If you have a stylesheet[TOMCAT_ROOT]/ZII/styles/cool.xsl that imports or includes a stylesheet library/valueformat.xsl then that will refer to the file [TOMCAT_ROOT]/ZII/styles/library/valueformat.xsl.

URIs in XSL-FO

If there is a relative URI in XSL-FO – (e.g. a reference to an image in an external file) – then this is interpreted as relative to a file zii.xml (which does not have to exist) in the base path of the ZII application.

e.g. If you have installed ZimWeb in the manner described in the installation instructions then specifying a reference to an image at path images/fop.jpg will refer to the file [TOMCAT_ROOT]/ZII/images/fop.jpg.

Security Guidelines for ZimWeb Applications

Key Guidelines for Creating Secure ZimWeb Applications
Secure access to the ZimWeb Administration servlet such 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 required, or track Zim sessions in the http session.
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 with the XML information output by the application. Remember that the client can specify `style=none` in any request to see the raw, unstyled XML data.

Introduction to ZimWeb

Adding More Power and Flexibility to Zim

Zim is a powerful and flexible environment for developing and using all types of database applications.

Zim‘s Entity-Relationship (ER) data model and fully-integrated Object Dictionary enable progressive program development, whether the information processing system is simple or complex. Zim Server provides a database server capability that can be used with ZIMQTC or other client processes.

The following topics describe ZimWeb, including its operations and how it can be used to create Web applications using Zim.

The Technology inside ZimWeb

ZimWeb has some distinct advantages over previous solutions, including:

It is an all-Java servlet – it runs on any platform with a Java Servlet Engine, such as Apache’s Tomcat
It makes web development for Zim applications easier with support for features such as client sessions, cookies, etc.
It supports XML and multiple client types (web browsers, cellphones and tablets, etc.) by integrating with the Apache’s Xalan-Java version 2 XSLT styling engine and Apache’s Formatting Object Processor.

To help you understand why these technologies are so useful for developing the Internet and other applications we recommend that you read the bibliography.

ZimWeb and Zim Server

ZimWeb makes use of ZIMSERVER to access Zim databases and connects a Zim Server to the internet. Thus, a good working knowledge of the Zim Server product is required for the development of Web applications using Zim.

This user guide describes the features and functions of ZimWeb. There is also a complete description of the implementation of the example application. Most Web applications using ZimWeb can be modeled after this example. Since the example does not use all features of ZimWeb, a number of additional topics provide reference information on software installation, configuration, etc.

ZimWeb Page Templates

ZimWeb includes page template support. This allows you to combine parameters from Zim with the page (web page, etc.) delivered to the client.

Template file format

A page template is just a regular page (HTML etc.), 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 parameters placeholders are formatted like HTML comments (e.g. so for a parameter named company you would use a parameter placeholder ).

Note: the parameter and the parameter placeholder must be in the same case.

The page template processor will substitute the value of the parameter for the parameter placeholder. If the value of a parameter in a placeholder is not supplied, its value will be assumed to be blank. You can use the same parameter placeholder more than once in a given template.

Sample template

customer.htm

Parameter XML format

The Zim application supplies the values of parameters in an XML format.

The root element can have any name. The parameter names are the names of the elements which are children of the root element. The character content of each of the children of the root element is the value of the parameter.

An easy way to demonstrate this is by the following example:

Sample XML data

Note: the use of the CDATA section in the above to allow the company parameter to include any characters. Alternatively the "&" character could have been replaced by its corresponding entity &.

ZimWeb Architecture

ZimWeb Connection Architecture

Web applications can be implemented in Zim, using a Java Servlet program called ZIIServlet, provided as part of ZimWeb. A Java Servlet must be executed on a Java Servlet Container, such as Apacheâ€™s Jakarta Tomcat.

ZIIServlet works together with Zim Server to process requests from the client, whose interaction with the end user occurs through a web browser. In particular, request parameters (e.g. HTML form field values) are passed as parameters to a Zim program that is executed on Zim Server. That program is responsible for processing the request and constructing the response. Although the response can be sent directly back to the client, ZimWeb includes a variety of options for processing it.

ZimWeb communicates with Zim Server using TCP/IP. Zim Server and ZimWeb, can run on the same or different systems, provided that there is a network connection between the them.

The following diagram shows the basic components of a Web application using ZimWeb:

ZimWeb Components

ZimWeb is composed of four components: the ZIIServlet, the Java Servlet Container, the Zim Database Agent and a web browser.

Java Servlet Container

Also known as a Java Servlet Engine. An environment in which Java Servlets can be executed. Tests were done with Apacheâ€™s Tomcat, which is the official reference platform for Java Servlet Containers. A Java Servlet Container can be run independently, or it can be integrated with a Web Server. The ZimWeb Reference Platform includes Tomcat, but a variety of alternatives are available.

ZIIServlet

ZIIServlet is a Java Servlet. It can be loaded automatically by the Java Servlet Container when the first request is received, or alternatively it can be loaded in advance so that it is ready beforehand.

Zim Database Agent

The Zim Database Agent is part of Zim Server. It is a process that runs on a specific machine and accesses a specific database. ZimWeb can communicate with any number of databases on any number of database machines. However, a Zim Database Agent is always connected to a specific database.

Web Browser

Typical web browsers include Microsoft Internet Explorer on Windows, Safari on MacOSX and iOS, Chrome, Firefox and Opera on serveral platforms, from desktops to tablets and smartphones. The web browser is not supplied with ZimWeb. End users will connect to ZimWeb using any available web browser in their machines

Bibliography

XML Technologies

The following books will be particularly useful in explaining the XML technologies that are crucial to using the ZimWeb effectively:

XML By Example (2nd Edition) and
Applied XML Solutions by
Benoit Marchal – these will give you a good overview of the XML landscape.
XSLT Programmer’s Reference 2nd Edition by
Michael Kay – this is the reference book for XSLT, though it is a bit “heavy” to get you started –
XML By Example (2nd Edition) is a much gentler introduction. But he knows his stuff – he wrote the
Saxon XSLT processor.
XSLT by
Doug Tidwell – he’s a “technology evangelist” from IBM.
XSLT Cookbook by
Sal Mangano
XSL-FO by
Dave Pawson.

Java

If you want to learn about Java then take a look at these books:

General Java programming

Learning Java, 2nd Edition by Patrick Niemeyer and Jonathan Knudsen – a great introduction to the Java language.
Java in a Nutshell, 4th Edition by David Flanagan, and Java Enterprise in a Nutshell, 2nd Edition by William Crawford, Jim Farley and David Flanagan – together, these provide a useful reference for the Java language.

Server-side Java programming

Java Servlet Programming, 2nd Edition by Jason Hunter with William Crawford – this is a very clear exposition of server-side Java programming.
Professional Apache Tomcat by lots of authors. This recently-published book is really helpful in trying to get the best out of the Tomcat servlet engine.

ML Processing with Java

Java & XML, 2nd Edition by Brett McLaughlin – this is an excellent explanation of this topic.
Java and XSLT by Eric M. Burke – another excellent O’Reilly book.

ZimWeb Administration

ZIIAdmin servlet is ZimWeb‘s administration tool. It can be used to manage ZimWeb either from the web or from a command line or script, which can be scheduled.

Web Administration

If you invoke the ZIIAdmin servlet from a web browser, you will see a page with various parts under different headings:-

Database Status	Allows 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. The current status of the Zim Database Agent sessions is indicated as “Database connections are RUNNING” or “… NOT RUNNING”. If the connections are running, then an adjacent button allows you to “Shutdown Database Connections”; if they are not running, then the button allows you to “Start Database Connections”.
Debug Status	Indicates whether client debugging capability is enabled or disabled – press the adjacent button to toggle the status as necessary.
Initialisation Parameters	Shows the values of the startup parameters for the ZimWeb .
XSLT Stylesheet cache	Indicates the current contents of the XSLT stylesheet cache. If you need to clear the cache – e.g. if you have changed an XSLT stylesheet which is cached into memory and thus will not be read – then click the adjacent button “Clear XSLT Stylesheet Cache”.
Page Template cache	Indicates the current contents of the page template cache. If you need to clear the cache – e.g. if you have changed a page template which is cached into memory and thus will not be read – then click the adjacent button “Clear Page Template Cache”.
FOP driver pool	Indicates the current number of FOP (Apache Formatting Object Processor) driver instances and the number checked out (in active use at the time that you start the web-administration tool). If the ZII receives more than one request for XSL-FO rendering at the same time then it will automatically increase the number of driver instances available. If you need to reset the FOP driver pool then click the adjacent button “Reset FOP Driver Pool”.

Command line or scripted administration

The ZIIAdmin servlet can also be invoked from the command line or by a script. The servlet itself requires two parameters:

✓ action – set to indicate what query or action the servlet is to perform. Permitted actions include:

✓ conn-status – return the status of the Zim Database Agent connections.

✓ conn-start – attempt to start the Zim Database Agent connections.

✓ conn-stop – attempt to stop the Zim Database Agent connections.

✓ debug-status – return the debug capability status.

✓ debug-enable – enable the debug capability.

✓ debug-disable – disable the debug capability.

✓ clear-style-cache – clear the XSLT stylesheet cache.

✓ clear-page-template-cache – clear the page template cache.

✓ reset-xslfo-driver-pool – reset the XSL/FO driver pool.

✓ content – set to text so that the servlet will return plain text instead of HTML.

CallURL utility

To enable the ZIIAdmin servlet to be called from the command line or a script, ZimWeb includes the CallURL utility to enable calls to a URL, with BASIC authentication details, if necessary.

The full syntax for CallURL is:

java -cp /zii.jar biz.zim.util.CallURL [ ]
to invoke the URL , optionally with BASIC authentication for user and password .

For example: To start the database connections on a local running ZimWeb installation or a default Tomcat installation, if the ZimWeb file zii.jar is in the current directory, and the ZIIAdmin servlet has security requiring the username admin and password friend, you could use the command:
java -cp zii.jar http://localhost:8080/ZII/servlet/ZIIAdmin?action=conn-start&content=text admin friend

Configuring ZimWeb

If you are using Tomcat, and have installed the ZimWeb in the manner described in the installation instructions, then the servlet configuration (servlet initialisation parameters) will be in the web.xml file in the [TOMCAT_ROOT]/webapps/ZII/WEB-INF directory. If you are using a different servlet engine, then you will have to consult its documentation to see how to configure it.

Here are the configuration parameters, organized by function type:

Automatic servlet loading
load-on-startup (Tomcat configuration parameter)	This controls whether the ZII servlet is loaded automatically when the Tomcat Java servlet engine starts. This means that the servlet is loaded and ready to run when the first client request arrives. Read the Tomcat documentation for more details on this subject. Note: This is not an initialisation parameter for the ZII servlet – it is a configuration parameter for the servlet. If you are using a different servlet engine then consult its documentation.
Automatically starting database connections
auto-start	This controls whether the ZII will automatically start the Zim Server agent sessions when the ZII servlet is loaded. If this equals `yes` (the default), then they are; it it is `no`, then they are not. If the ZII receives a client request, and the agents are not started, then the client will receive an error indicating that the database connection have not been started.
Configuration and log files
config-file	This gives the file name of the Zim Server agent configuration file – the same file that the ZimCGI uses. Consult the ZimCGI documentation and Configuration file extensions for more details on this subject.
log-file	This gives the file name of the log file that the ZII write – equivalent to the zimcgisrv.log file that the ZimCGI generates. Consult the ZimCGI documentation for more for more details on this subject.
verbose	This controls whether certain aspects of the logging features of the ZII are more verbose than usual (and necessary!). If it is yes, then the logging is more verbose. If it is no (the default), then your logs are not so verbose. Consult the ZimCGI documentation for more for more details on this subject.
Controlling XSLT processing
use-xslt-output-type	This controls how the ZII sets the mime content type of the response, if the output is passed through the XSLT processor and there is no content-type: command. If it is no (the default), then the content type is assumed to be `text/html`. If it is yes, then the XSLT processor will extract the content type from the clause in the stylesheet. If you set this to yes and you do not have an clause in the XSLT stylesheets, then the XSLT processor will usually assume the content type is XML (text/xml), which may not be what you want. I don’t think there is a good reason for you not to put an clause in all of your XSLT stylesheets. N.B. for more details on this subject please see documentation on XSLT.
Session and cookie management
default-session-timeout	This is the default session timeout in seconds. If not specifed, ZII will default to a 1 hour timeout. This can be overridden for a particular session by using the session-timeout: command.
default-cookie-timeout	This is the default cookie expiry time in seconds. If not specifed, ZII will default to a 1 year expiry. This can be overridden for a particular cookie by using the cookie-timeout: command.
Persistent Zim sessions
zim-session-security	This controls the security of persistent Zim sessions; the various options are:- `open` – insecure, as with the previous ZimCGI – the client can initiate a Zim session through the SESSIONID parameter without restriction. `disable-start` – ignore requests to start a persistent Zim session in the input parameters (i.e. a blank SESSIONID parameter). You can start the persistent Zim session with the `start-zim-session` command instead. `restrict-start` – ignore requests to start a persistent Zim session in the input parameters (i.e. a blank SESSIONID parameter) if the parameter TEMPLATE does not include the SESSIONID parameter. This is the default setting, which should work with existing ZimCGI applications. This should be combined with specifying all the parameter templates in the “Security” declarations in the configuration file, of course. `restrict-continue` – prevent starting or continuing a persistent Zim session in the input parameters (i.e. a SESSIONID parameter – blank or not – without also an ENDSESSION or CANCELSESSION parameter) if the parameter TEMPLATE does not include the SESSIONID parameter. `http-session` – the input parameters SESSIONID, ENDSESSION and CANCELSESSION are ignored; instead, ZimWeb stores the SESSIONID automatically in the HTTP session; and it is the exclusive responsibility of the Zim application to start and stop persistent Zim sessions through the start-zim-session, end-zim-session and cancel-zim-session commands; also, it is not necessary to have the SESSIONID in the parameter TEMPLATE, nor output the SESSIONID into a hidden field. `disable` – the input parameters SESSIONID, ENDSESSION and CANCELSESSION are ignored.
Debugging
allow-debug	This is the default state of the client debug capability. If `yes` then the client debug capability will initially be enabled when the ZII is started; if `no` (the default value) them it will initially be disabled.

Configuration File Extensions

Specified parameter templates

Security With ZimCGI, you can specify the Zim procedures that may be executed in a list following the Security tag(s) for each connection.
In addition, the ZII allows you to specify the parameter template in parentheses after the procedure name.
e.g. Security MyProc(CC) specifies that MyProc is an allowed procedure, and that the parameter template is (CC), eliminating the need to specify a TEMPLATE parameter.
If a parameter template is specifed in the configuration file, this will override any TEMPLATE parameter in the request.

Specified parameter templates
Security	With ZimCGI, you can specify the Zim procedures that may be executed in a list following the Security tag(s) for each connection. In addition, the ZII allows you to specify the parameter template in parentheses after the procedure name. e.g. Security MyProc(CC) specifies that MyProc is an allowed procedure, and that the parameter template is (CC), eliminating the need to specify a TEMPLATE parameter. If a parameter template is specifed in the configuration file, this will override any `TEMPLATE` parameter in the request.

Zim Applications’ Input Parameters

Input parameters are those parameters supplied as input to the Zim application.

Parameters tend to work in the same way as the ZimCGI, except that:

The TEMPLATE parameter is required, except where a default parameter template has been specifed for a procedure.
There are more parameters with reserved meanings – namely PATHINFO, STYLE, PAGETEMPLATE and RENDER.
Parameters can come from HTTP sessions and cookies as well as form input.
Form parameters can come from both POST and GET requests.

N.B. Parameter names are not case sensitive.

Parameter sources

Input parameters can come from three different sources:

Form parameters (i.e. POST/GET).
Session parameters.
Cookie parameters.

You must specify the parameters to be passed to your Zim application in the TEMPLATE parameter, or the default parameter template for the procedure.

Normally, 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.

However, if a parameter has a name beginning with the prefix session. e.g. session.IsLoggedIn then it can only come from the HTTP session parameters.

Similarly, if a parameter has a name beginning with the prefix cookie. e.g. cookie.UserName then it can only come from the cookie parameters.

Parameters with new or changed meanings

Parameters with new or changed meanings, compared with the ZimCGI, are:

ZimCGI parameters which have been modified
`TEMPLATE`	The meaning and format of this parameter has not been changed, but it is required (unlike the ZimCGI), unless the procedure has a default parameter template.
`DEBUG`	The meaning and format of this parameter has not been changed – if you set the parameter `DEBUG` to any value in the request parameters then the debugging information will be sent to the client. However, the debugging information is a lot more comprehensive, including the raw output of the Zim database agent. Note: For security reasons, any commands in the Zim database agent output are not processed in a `DEBUG` request. Note also that a request for debugging information from a client will be ignored unless debug capability has been enabled.
Request information parameters
`PATHINFO`	The PathInfo of the request is placed in the `PATHINFO` parameter, which you can place in your `TEMPLATE`. 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`.
`REQUESTURL`	The URL the client entered; N.B. this includes any PathInfo, but excludes any parameters.
`SESSIONFROMCOOKIE`	Set to `1` if the client HTTP session is being tracked through a cookie (e.g. the `JSESSIONID` cookie in Tomcat), otherwise `0`. N.B. This will be set on the second and subsequent calls to the servlet – the session is not set up the first time a client invokes the servlet. Of course, HTTP session tracking through cookies requires that cookies be enabled on the browser.
`SESSIONFROMURL`	Set to `1` if the client http session is being tracked through URL rewriting, otherwise `0`. N.B. Session tracking does not currently work effectively through URL rewriting – instead you should track sessions by enabling cookies on the browser.
Authentication parameters
`AUTHUSERNAME`	The user authenticated by the web server.
`AUTHTYPE`	The authentication method used by the web server – BASIC etc.
`CLIENTUSERNAME`	The (not necessarily authenticated) user name the client is claiming.
`CLIENTPASSWORD`	The (not necessarily authenticated) password the client is claiming.
XSLT styling parameters
`STYLE`	This parameter indicates that a particular XSLT stylesheet is to be applied to the output of the Zim Server agent. If the Zim Server agent output includes an `apply-xslt:` command, then the stylesheet specified in the `STYLE` parameter overrides the that specified by the `apply-xslt:` command. The `STYLE` parameter specifies a file path relative to the base path of the ZimWeb application. If you have installed the ZimWeb in the manner described in the installation instructions then specifying `STYLE` as `/styles/cool.xsl` will refer to the file `[TOMCAT_ROOT]/ZII/styles/cool.xsl`. If you specify `STYLE=NONE` then the Zim agent output (presumably XML) will be returned as-is, without the application of any XSLT or form template processing. Note: specifying a `STYLE` automatically suppresses any XSL-FO rendering specified by the Zim Server agent, unless the `RENDER` parameter is also supplied.
Page template parameters
`PAGETEMPLATE`	This parameter indicates that a particular page template is to be applied to the output of the Zim Server agent. If the Zim Server agent output includes an `apply-page-template:` command, then the page template specified in the `PAGETEMPLATE` parameter overrides the that specified by the `apply-page-template:` command. The `PAGETEMPLATE` parameter specifies a file path relative to the base path of the ZimWeb application. If you have installed the ZimWeb in the manner described in the installation instructions then specifying `PAGETEMPLATE` as `/styles/fancy.html` will refer to the file `[TOMCAT_ROOT]/ZII/styles/fancy.html`. Read more about ZII page templates. If you specify `PAGETEMPLATE=NONE` then the Zim agent output (presumably XML) will be returned as-is, without the application of any XSLT or form template processing. Note: specifying a `PAGETEMPLATE` automatically suppresses any XSL-FO rendering specified by the Zim Server agent, unless the `RENDER` parameter is also supplied.
XSL Formatting Objects parameters
`RENDER`	This parameter indicates that the Zim agent output, or the result of the other content processing (typically XSLT), is to be treated as XSL Formatting Objects and rendered according to the `RENDER` parameter. The two rendering options currently available are PDF (Adobe Portable Document Format), for which you would specify the value `PDF`, or alternatively RTF (Rich Text Format), for which you would specify the value `RTF`.. Note: that rendering to PDF is much more accurate than rendering to RTF. If you specify `RENDER=NONE` then rendering is suppressed, and the XSL-FO is returned directly to the browser.

Page Templates

fbarbosafbarbosa112003-01-24T16:51:00Z2003-01-24T16:53:00Z32711549ZIM Technologies12319029.3821

Page Templates

ZimWeb includes page template support. This allows you to combine parameters from Zim with the page (web page, etc.) delivered to the client.

Template file format

The parameters placeholders are formatted like HTML comments (e.g. so for a parameter named company you would use a parameter placeholder ).

Note: the parameter and the parameter placeholder must be in the same case.

Sample template `customer.htm`

`Customer Details`

Customer Code
Customer Name

Parameter XML format

The Zim application supplies the values of parameters in an XML format.

An easy way to demonstrate this is by the following example:

Sample XML data

1007

Note the use of the CDATA section in the above to allow the company parameter to include any characters. Alternatively the “&” character could have been replaced by its corresponding entity &.