A structure which is used to "qualify" a column. Specifies that the column value in a given column identified by column id is to be compared via a specific operator to a particular DataValueDescriptor value.

The implementation of this interface is provided by the client; the methods of Qualifier are the methods the access code uses to use it.

Arrays of qualifiers are provided to restrict the rows returned by scans. A row is returned from a scan if all qualifications in the array return true.

A qualification returns true if in the following pseudo-code compare_result is true.

if (qualifier.negateCompareResult())
{
    compare_result = 
    row[(qualifier.getColumnId())].compare(
      qualifier.getOperator(), 
      qualifier.getOrderable(),
      qualifier.getOrderedNulls(), 
      qualifier.getUnknownRV()) 
    if (qualifier.negateCompareResult())
    {
        compare_result = !(compare_result);
    }
}

Qualifiers are often passed through interfaces as a set of Qualifiers, rather than one at a time, for example see the qualifier argument in TransactionController.openScan().

To make this consistent the following protocols are to be used when passing around sets of Qualifiers.

A single dimensional array is to be used to pass around a set of AND'd qualifiers. Thus qualifier[] argument is to be treated as:

    qualifier[0] AND qualifer[1] ... AND qualifier[qualifer.length - 1]

A two dimensional array is to be used to pass around a AND's and OR's in conjunctive normal form. The top slot of the 2 dimensional array is optimized for the more frequent where no OR's are present. The first array slot is always a list of AND's to be treated as described above for single dimensional AND qualifier arrays. The subsequent slots are to be treated as AND'd arrays of OR's. Thus the 2 dimensional array qual[][] argument is to be treated as the following, note if qual.length = 1 then only the first array is valid and it is and an array of AND clauses:

(qual[0][0] AND qual[0][0] ... AND qual[0][qual[0].length - 1])
AND
(qual[1][0] OR  qual[1][1] ... OR  qual[1][qual[1].length - 1])
AND
(qual[2][0] OR  qual[2][1] ... OR  qual[2][qual[2].length - 1])
...
AND (qual[qual.length - 1][0] OR  qual[1][1] ... OR  qual[1][2])

If any of the array's qual[0].length ... qual[qual.length -1] are 0 length they will be evaluated as TRUE; but they must be not NULL. See Example 4 for encoding of (a or b) that takes advantage of this.

Note that any of the arrays qual[0].length ... qual[qual.length -1] may also be of length 1, thus no guarantee is made the presence of OR predicates if qual.length < 1. See example 1a.

The following give pseudo-code examples of building Qualifier arrays:

Example 1: "a AND b AND c"

  qualifier = new Qualifier[1][3]; // 3 AND clauses

  qualifier[0][0] = a
  qualifier[0][1] = b
  qualifier[0][2] = c

Example 1a "a AND b AND c" - less efficient than example 1 but legal

  qualifier = new Qualifier[3]; // 3 AND clauses
  qualifier[0] = new Qualifier[1];
  qualifier[1] = new Qualifier[1];
  qualifier[2] = new Qualifier[1];

  qualifier[0][0] = a
  qualifier[1][0] = b
  qualifier[2][0] = c

Example 2: "(f) AND (a OR b) AND (c OR d OR e)" Would be represented by an array that looks like the following:

  qualifier = new Qualifier[3]; // 3 and clauses
  qualifier[0] = new Qualifier[1]; // to be intitialized to f
  qualifier[1] = new Qualifier[2]; // to be initialized to (a OR b)
  qualifier[2] = new Qualifier[3]; // to be initialized to (c OR d OR e)

  qualifier[0][0] = f
  qualifier[1][0] = a
  qualifier[1][1] = b
  qualifier[2][0] = c
  qualifier[2][1] = d
  qualifier[2][2] = e

Example 3: "(a OR b) AND (c OR d) AND (e OR f)"

  qualifier = new Qualifier[3]; // 3 and clauses
  qualifier = new Qualifier[4]; // 4 and clauses
  qualifier[0] = new Qualifier[1]; // to be intitialized to TRUE
  qualifier[1] = new Qualifier[2]; // to be initialized to (a OR b)
  qualifier[2] = new Qualifier[2]; // to be initialized to (c OR d)
  qualifier[3] = new Qualifier[2]; // to be initialized to (e OR f)

  qualifier[0][0] = TRUE
  qualifier[1][0] = a
  qualifier[1][1] = b
  qualifier[2][0] = c
  qualifier[2][1] = d
  qualifier[3][0] = e
  qualifier[3][1] = f

Example 4: "(a OR b)"

  qualifier = new Qualifier[2]; // 2 and clauses
  qualifier[0] = new Qualifier[0]; // 0 length array is TRUE
  qualifier[1] = new Qualifier[2]; // to be initialized to (a OR b)

  qualifier[1][0] = a
  qualifier[1][1] = b