[ You are here:
XTF ->
Deployment Guide -> Configuring crossQuery ]
Configuring the crossQuery Servlet
The
crossQuery servlet is responsible for taking a user search query and locating all files in the document library that match the specified search criteria. The resulting matches are then displayed in an HTML web page for the user to browse. The organization of the crossQuery servlet can be illustrated as follows:

The crossQuery servlet is configured by modifying one or more of the following files:
- The crossQuery.conf Configuration File
- The queryGen.xsl Request Parser
- The errorGen.xsl Error Page Generator
- One or more Document Formatter stylesheets
Each of these stylesheet templates is discussed in turn in the following subsections.
The crossQuery.conf Configuration File
The
crossQuery.conf configuration file is used by the
crossQuery servlet to locate its
Query Generator 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
crossQuery.conf can be found in the
conf subdirectory below the servlet base directory (i.e., the
XTF_HOME directory), or you can view it
online at SourceForge.
<crossQuery-config>
<logging level="LoggingLevel"/>
<queryParser path="LocationOfQueryParser"/>
<errorGen path="LocationOfErrorPageGenerator"/>
<stylesheetCache size="Entries" expire="Seconds"/>
<dependencyChecking check="YesOrNo"/>
<reportlatency enable="YesOrNo" {cutoffSize="NumBytes"}/>
<runawaytimer {normalTime="Seconds"} {killTime="Seconds"}/>
<trackSessions track="YesOrNo"/>
<!-- Your tags go here -->
</crossQuery-config>
These tags and attributes have the following meanings:
<logging level="LoggingLevel"/> |
This tag is an optional tag that sets the level of logging output by the crossQuery 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 crossQuery servlet defaults to displaying informational (info) level messages. |
<queryParser path="LocationOfQueryParser"/> |
This tag specifies the name and path to the XSLT template used by the crossQuery servlet to convert incoming search query URLs to the internal XML search query 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, see the comments in the sample queryParser.xsl file. |
<errorGen path="LocationOfErrorPageGenerator"/> |
When an error occurs (either 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 file. |
<stylesheetCache size="Entries" expire="Seconds"/> |
This tag (if specified) overrides the defaults number of entries and the expiration time (in seconds) for the styleSheetCache, which maintains compiled versions of the XSLT templates used by the crossQuery servlet. Usually, these attributes need not be changed. |
<dependencyChecking check="YesOrNo"/> |
Whenever consulting one of its internal caches, the crossQuery 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"}/> |
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. |
<runawaytimer {normalTime="Seconds"} {killTime="Seconds"}/> |
Controls whether the servlet tracks, reports, and optionally kills potential "runaway" requests. See the discussion of runaway timing 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. Generally, this should only be enabled if you plan to store and use session data. |
Latency reporting
When the
<reportLatency> element's
report attribute 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.
Runaway timing
The
<runawayTimer> element'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.
The queryParser.xsl Query Parser
The
queryParser.xsl template describes how the
crossQuery servlet should translate search query URLs into internal XML based search queries. A sample
queryParser.xsl is provided in the
style/crossQuery/queryParser/default subdirectory below the
XTF_HOME base directory under which the XTF system was installed, or you can look at it
online at SourceForge. A full discussion of the internal workings of the Query Parser is contained in the
XTF Programming Guide.
The errorGen.xsl Error Page Generator
The
errorGen.xsl template describes how the
crossQuery 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/crossQuery subdirectory below the
XTF_HOME base directory under which the XTF system was installed, or you can look at it
online at SourceForge. A full discussion of the internal workings of the Error Generator is contained in the
XTF Programming Guide.
The Search Result Formatters
Any number of templates can exist to describe how the
crossQuery servlet should translate the XML search results into HTML that can be displayed in the user's browser. Which formatter to use is determined by a tag in the
Query Parser stylesheet. A sample search result formatter is provided in the
style/crossQuery/resultFormatter/default subdirectory below the
XTF_HOME base directory under which the XTF system was installed, or you can look at it
online at SourceForge. The formatter is called
resultFormatter.xsl . A full discussion of the internal workings of the search result formatter is contained in the
XTF Programming Guide.
Running the crossQuery Servlet
As with the
dynaXML servlet, once your servlet container has been configured to invoke it, running the
crossQuery servlet consists of simply issuing a valid search query URL.