[ You are here: XTF -> Deployment Guide -> Configuring dynaXML ]

Configuring the dynaXML Servlet

The dynaXML servlet is responsible for taking a request for a document, converting it to XML if necessary, optionally authenticating the user, and finally presenting the document as a web page. The organization of the dynaXML servlet can be illustrated as follows:
dynaXMLDataFlow.gif

Table of Contents

Configuring the dynaXML Servlet
The dynaXML.conf Configuration File
Latency reporting
Stylesheet profiling
Runaway timer
Lazy trees
The docReqParser.xsl Request Parser
The errorGen.xsl Error Page Generator
The dynaXML Document Formatters
Running the dynaXML Servlet
The dynaXML servlet is configured by modifying one or more of the following files:
Each of these files is discussed in turn in the following subsections.

The dynaXML.conf Configuration File

The dynaXML.conf configuration file is used by the dynaXML servlet to locate its Document Request Parser and Error Page Generator XSLT templates. It is also used to adjust the behavior of the servlet itself. Each tag and its associated attributes are discussed here, and a sample dynaXML.conf can be found in the conf subdirectory below the servlet base directory (i.e., the XTF_HOME directory.), or you can see it online at SourceForge.
<dynaXML-config>
 
    <logging level="LoggingLevel"/>
 
    <docReqParser path="LocationOfRequestParser" params="ParamsToPass"/>
    <errorGen path="LocationOfErrorPageGenerator"/>
 
    <reverseProxy IP="ddd.ddd.ddd.ddd" marker="MarkerString"/>
 
    <stylesheetCache size="Entries" expire="Seconds"/>
    <ipListCache size="Entries" expire="Seconds"/>
    <authCache size="Entries" expire="Seconds"/>
    <loginCache size="Entries" expire="Seconds"/>
 
    <dependencyChecking check="YesOrNo"/>
    <reportlatency report="YesOrNo" {cutoffSize="NumBytes"}/>
    <stylesheetProfiling profile="YesOrNo"/>
    <runawaytimer {normalTime="Seconds"} {killTime="Seconds"}/>
    <trackSessions track="YesOrNo"/>
    <lazyFiles use="YesOrNo" buildAlone="YesOrNo"/>
 
    <!-- Put pass-through tags here, if you need any. -->
 
</dynaXML-config>

These tags and attributes have the following meanings:

<logging level="LoggingLevel"/> This optional tag sets the level of logging output by the dynaXML servlet. The possible output levels are defined as follows: errors: Only error messages are displayed. warnings: Both error and warning messages are displayed. info: Error, warning, and informational messages are displayed. debug: Low level debug output is displayed in addition to error, warning, and informational messages. If this argument is not specified, the dynaXML servlet defaults to displaying informational (info) level messages.
<docReqParser path="LocationOfDocReqestParser"/> This is a required tag. The path attribute specifies the name and path to the XSLT template used by the dynaXML servlet to convert incoming document request URLs to the internal XML format actually used by the servlet. The path is interpreted relative to the servlet's base (i.e., the directory assigned to XTF_HOME. ) For a more detailed description of this tag, see the comments in the sample docReqParser.xsl file. Note: the old params attribute is obsolete and is silently ignored if specified.
<errorGen path="LocationOfErrorPageGenerator"/> This is a required tag. When an error occurs (either user authentication or an internal error), the XSLT template specified by this configuration tag is used to produce a nicely formatted error page for the requestor. The path is interpreted relative to the servlet's base (i.e., the directory assigned to XTF_HOME. ) For a more detailed description, see the comments in the sample errorGen.xsl files.
<reverseProxy IP="ddd.ddd.ddd.ddd" marker="MarkerString"/> This optional tag is only required if IP-based authentication uses a reverse proxy server. Using this tag tells dynaXML servlet that the incoming IP address belongs to the reverse proxy server, and that the actual requestor's IP address must be read from the X-Forwarded-For marker in the HTTP Request Header. Set the IP attribute to the IP address for the reverse proxy server. Use the marker attribute if you wish to tell the dynaXML servlet to use a forwarding marker other than the default X-Forwarded-For marker.
<stylesheetCache size="Entries" expire="Seconds"/>, etc. These optional tags override the defaults number of entries and the expiration time (in seconds) for the various caches maintained by the servlet. Usually, these values need not be changed. styleSheetCache: Compiled versions of stylesheets (request parser, doc formatter, etc.). ipListCache: Compiled versions of IP lists (used only for IP-address based authentication.) authCache: Session IDs of successful authentication attempts (LDAP or external.) When expired, the user will be forced to log in again. loginCache: Security info for external logins, to verify authentication when user returns from the external page. If it expires while user is logging in, they will be forced to try again.
<dependencyChecking check="YesOrNo"/> This optional tag specifies whether dynaXML should perform dependency checking. Whenever consulting one of its internal caches, the dynaXML servlet can optionally check if the source file(s) have been changed and if so ignore the cache entry and reload the file(s). This hurts performance slightly, but makes testing and development much easier. Set this to no for a production system where every last little bit of speed is critical. Otherwise, set it to yes.
<reportlatency report="YesOrNo" {cutoffSize="NumBytes"}/> This optional tag controls whether the servlet will report the latency of each request, that is, how long each request took to process and deliver to the client. See the discussion of latency reporting below.
<stylesheetProfiling profile="YesOrNo"/> Controls whether a profile is generated for each document request. See the discussion of stylesheet profiling below.
<runawaytimer {normalTime="Seconds"} {killTime="Seconds"}/> Controls whether the servlet tracks, reports, and optionally kills potential "runaway" requests. See extended discussion below.
<trackSessions track="YesOrNo"/> Controls whether the servlet associates a session with each request. If enabled, a session will be created the first time a given user connects to the servlet. The session is assigned a unique identifier which is passed through on subsequent page views either through a cookie or by encoding the session identifier in the URL. The main purpose of sessions is to store long-lasting or large data items that would be inconvenient to pass as URL parameters. The data can be stored and retrieved using XSL extension functions available in XTF. See Tracking Session State in the XTF Programmer's Guide for details. This should generally be enabled.
<lazyTrees use="YesOrNo" buildAlone="YesOrNo"/> Controls whether the servlet uses (and optionally builds by itself) lazy trees. See extended discussion below.

Latency reporting

When the <reportLatency> tag's report is set to yes, the servlet will record and log how many milliseconds were spent processing each request (regardless of whether the request succeeded or produced an error page.) This information can be useful for accumulating statistical data, or to target optimization efforts on those requests that took longest to serve. Set it to no if you want to avoid logging and don't need the information.

Depending on the data you're looking for, you might want to exclude latency of large requests (e.g. a whole book). To do this, set the cutoffSize attribute to a number of bytes; when any request has output that much data, the servlet will report the latency immediately, labeled "Latency (cutoff)". When the request finally completes, the total latency will be reported with the label "Latency (final)". Leaving out the cutoffSize attribute, or setting it to zero, disables cutoff reporting.

Latency reporting has very little impact on system performance, so is safe to enable in production environments.

Note: The reports are logged at the "info" level, so if the <logging> level above is set to warnings or errors, nothing will appear.

Stylesheet profiling

A profile identifies the stylesheet and line number of each XSLT command that was executed for the query, and a relative count that identifies roughly how long it took to execute that command. Within the profile, the executed commands are ordered such that the most used commands appear first, and the least used commands appear last. This provides clues as to where the stylesheet is spending its time and thus could possibly be optimized. When enabled, profiles are written to the dynaXML servlet's activity log. Set this to no for general use, since collecting the profile information can be time-consuming.

Note: The profile information is logged at the "info" level, so if the <logging> level above is set to warnings or errors, nothing will appear.

Runaway timer

The <runawaytimer> tag's normalTime attribute specifies the maximum amount of time, in seconds, that requests are generally expected to take. Any requests that exceed this time will be logged (with a call stack trace on Java 5.0 and above.) If set to zero or not specified, no logging of potential runaway requests will be performed. The killTime attribute specifies the time after which a request is truly considered runaway and should be killed. After this time is exceeded a flag is set, and many of the major processing loops in XTF will check the flag and kill off the request. However, some parts (deeply buried in third-party libraries) do not check this flag and thus the request might not be successfully killed. If set to zero, threads will never be killed before they complete.

Runaway timing can introduce significant overhead, and should be enabled only if one is experiencing problems that might be due to runaway requests. Set these to zero for general use.

Note: Runaway reports are logged at the "info" level, so if the <logging> level above is set to warnings or errors, nothing will appear.

Lazy trees

The <lazyTrees> tag's use attribute controls whether dynaXML will use "lazy trees." These files are generally speed processing. If not specified, this attribute defaults to "yes" For detailed information on lazy trees see XTF Under the Hood.

The buildAlone attribute controls whether dynaXML will create lazy trees if they're not already built by the textIndexer. If not specified, this attribute defaults to "no". Most users will want to leave this at its default "no" to ensure that the indexer keeps the lazy trees in sync with the index at all times. However, if you are using dynaXML completely independently, without using textIndexer, then enable buildAlone to build lazy trees in dynaXML.


The docReqParser.xsl Request Parser

The docReqParser.xsl template describes how the dynaXML servlet should translate external document request URLs into internal XML based document requests. As part of the translation, the template can also optionally request authentication of the user that made the document request. A sample docReqParser.xsl is provided in the conf subdirectory below the XTF_HOME base directory under which the XTF system was installed. You can also look at it online at SourceForge A full discussion of the internal workings of docReqParser.xsl is contained in the XTF Programming Guide.


The errorGen.xsl Error Page Generator

The errorGen.xsl template describes how the dynaXML servlet should generate an HTML page whenever there is an error that needs to be reported back to the user. A sample errorGen.xsl is provided in the style/dynaXML subdirectory below the XTF_HOME base directory under which the XTF system was installed. You can also see it online at SourceForge. A full discussion of the internal workings of errorGen.xsl is contained in the XTF Programming Guide.


The dynaXML Document Formatters

Any number of templates can exist to describe how the dynaXML servlet should translate the XML file for a document in the library into HTML that can be displayed in the user's browser. Which document formatter to use is determined by a tag in the docReqParser.xsl template. Sample document formatters are provided in the style/dynaXML/docFormatter/tei and style/dynaXML/docFormatter/ead subdirectories below the XTF_HOME base directory under which the XTF system was installed. The document formatters are similar but implement different output formatting schemes. A full discussion of the internal workings of the document formatter templates is contained in the XTF Programming Guide.


Running the dynaXML Servlet

Assuming that the servlet container you are using has been configured to invoke it, running the dynaXML servlet consists of simply issuing a valid document request URL. A sample request was illustrated in the Quick Start section entitled Verify that Document Retrieval (dynaXML Servlet) Works.