org.z3950.zing.cql
Class CQLGenerator

java.lang.Object
  org.z3950.zing.cql.CQLGenerator

public class CQLGenerator
extends java.lang.Object

A generator that produces random CQL queries.

Why is that useful? Mainly to produce test-cases for CQL parsers (including the CQLParser class in this package): you can generate a random search tree, render it to XCQL and remember the result. Then decompile the tree to CQL, feed the generated CQL to the parser of your choice, and check that the XCQL it comes up with is the same what you got from your initial rendering.

This code is based on the same grammar as the CQLParser class in this distribution - there is a generate_x() method for each grammar element X.

Version:

$Id: CQLGenerator.java,v 1.9 2007-07-03 15:41:35 mike Exp $

See Also:

http://zing.z3950.org/cql/index.html

Constructor Summary

CQLGenerator(java.util.Properties params)
Creates a new CQL generator with the specified parameters.

Method Summary

CQLNode	generate() Generates a single random CQL query.
static void	main(java.lang.String[] args) A simple test-harness for the generator.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CQLGenerator

public CQLGenerator(java.util.Properties params)

Creates a new CQL generator with the specified parameters.

Parameters:

params - A Properties table containing configuration parameters for the queries to be generated by this generator. Recognised parameters are:

seed

If specified, this is a long used to seed the random number generator, so that the CQL generator can be run repeatably, giving the same results each time. If it's omitted, then no seed is explicitly specified, and the results of each run will be different (so long as you don't run it more that 2^32 times :-)

complexQuery

[mandatory] A floating-point number between 0.0 and 1.0, indicating the probability for each cql-query node that it will be expanded into a ``complex query'' (cql-query boolean search-clause) rather than a search-clause.

complexClause

[mandatory] A floating-point number between 0.0 and 1.0, indicating the probability for each search-clause node that it will be expanded into a full sub-query rather than an [ index relation ] term triplet.

proxOp

[mandatory] A floating-point number between 0.0 and 1.0, indicating the probability that each boolean operator will be chosen to be proximity operation; otherwise, the three simpler boolean operations (and, or and not) are chosen with equal probability.

equalsRelation

[mandatory] A floating-point number between 0.0 and 1.0, indicating the probability that each relation will be chosen to be = - this is treated as a special case, since it's likely to be by far the most common relation in ``real life'' searches.

numericRelation

[mandatory] A floating-point number between 0.0 and 1.0, indicating the probability that a relation, having chosen not to be =, is instead chosen to be one of the six numeric relations (<, >, <=, >=, <> and =).

Method Detail

generate

public CQLNode generate()
                 throws MissingParameterException

Generates a single random CQL query.

Uses the parameters that were associated with the generator when it was created. You are free to create as many random queries as you wish from a single generator; each of them will use the same parameters.

Returns:

A CQLNode that is the root of the generated tree. That tree may be rendered in XCQL using its toXCQL() method, or decompiled into CQL using its toCQL method.

Throws:

MissingParameterException

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

A simple test-harness for the generator.

It generates a single random query using the parameters specified in a nominated properties file, plus any additional name value pairs provided on the command-line, and decompiles it into CQL which is written to standard output.

For example, java org.z3950.zing.cql.CQLGenerator etc/generate.properties seed 18398, where the file generate.properties contains:

        complexQuery=0.4
        complexClause=0.4
        equalsRelation=0.5
        numericRelation=0.7
        proxOp=0.0
 

yields:

        ((dc.author = "<xml.element>") or (bath.title = cat)) and
                (dc.subject >= "the complete dinosaur")
 

Parameters:

configFile - The name of a properties file from which to read the configuration parameters (see above).

name - The name of a configuration parameter.

value - The value to assign to the configuration parameter named in the immediately preceding command-line argument.

Throws:

java.lang.Exception