[ You are here: XTF -> Programming -> Error Generator ]

Error Generator Programming for crossQuery and dynaXML

It's not a perfect world, and errors happen. For the times when they do, the crossQuery and dynaXML servlets include a handy stylesheet-based mechanism to put a nice face on things, creating a formatted HTML page letting the user know what happened, and potentially how to fix it. This stylesheet is called the Error Generator.

Here are the main sources of errors that activate the servlets' error handling mechanisms:
  1. Configuration errors, such as invalid parameters in the crossQuery.conf or dynaXML.conf file, or missing stylesheets.
  2. Errors detected by the Query Parser stylesheet. It lets the servlet know something went wrong by outputting an <error> tag instead of the normal <query> tag.
  3. Incorrect syntax in the <query> tag produced by the Query Parser.
  4. Incorrect syntax in the tags produced by the Document Request Parser.
  5. Problems that occur while the Text Engine is reading the input document or executing a query. Some such errors include trying to query a document that hasn't been indexed, or attempting a wildcard query on too many terms.
  6. Bugs in the XTF system itself (hopefully very rare.)
In all these cases, the servlet looks in the crossQuery.conf or dynaXML.conf file for the <errorGen> tag that specifies an Error Generator stylesheet to run. The servlet constructs a small input document with details about the particular error and passes it to the Error Generator, whose job is to output a nice-looking error page.

For instance, the following query will create an error with the sample distribution (it performs a wildcard query on all terms):
This exceeds the default limit on the number of terms a query can access, so crossQuery calls the Error Generator with the following input:
<TermLimit>
   <message>
     Wildcard query on 'text' matched too many terms (more than 1000).
     First 50 matches: $ + 0 0.0 0.00 0.0001 0.001 0.0015 0.0029 0.003
     0.0034 0.004 0.005 0.006 0.007 0.008 0.009 0.01 0.010 0.011 0.012
     ...more terms here...
   </message>
</TermLimit>
Writing the XSLT code that transforms the various error tags is beyond the scope of this document, but the default Error Generator included with the XTF distribution is a good place to start. It can be found in the style/crossQuery or style/dynaXML directory (depending on which servlet you're working with).

An easy way to check the input to your Error Generator is to add ;raw=1 to your query URL. When an error occurs, the servlet will dump the raw XML to the browser, instead of sending it to the stylesheet.

Each kind of error specifies different information for the Error Generator to work on. For instance, authentication failures include the requestor's IP address, whereas internal errors include a Java stack trace. For a full list of the various errors that may be sent by crossQuery and dynaXML to the Error Generator, please consult the Error Generator Stylesheet Reference.