tribble.search
Class DocumentQueryFilter

java.lang.Object
  extended bytribble.search.DocumentQueryFilter
All Implemented Interfaces:
DocumentFilterI

public class DocumentQueryFilter
extends java.lang.Object
implements DocumentFilterI

Generic document entry filter.

Interprets simple SQL-like queries to select documents.

Query Syntax

The following query syntax is supported: query-expr: or-expr or-expr: and-expr and-expr 'OR' or-expr and-expr: cmp-expr cmp-expr 'AND' not-expr not-expr: cmp-expr 'NOT' not-expr cmp-expr: operand operand ['NOT'] '=' operand operand ['NOT'] '<>' operand operand ['NOT'] '<' operand operand ['NOT'] '<=' operand operand ['NOT'] '<' operand operand ['NOT'] '<=' operand operand ['NOT'] 'CONTAINS' string operand ['NOT'] 'LIKE' text-pattern operand ['NOT'] 'LIKEFILE' filename-pattern operand ['NOT'] 'IN' '(' operand-list ')' operand ['NOT'] 'BETWEEN' operand 'AND' operand operand 'IS' ['NOT'] 'NULL' operand-list: operand operand [','] operand-list operand: '(' or-expr ')' name-expr number date-string name-expr: name string name-expr '.' name name-expr '.' string name-expr '[' operand ']'

A name operand is a document attribute, or one of the following predefined attributes:

    name        - Document name (string)
    size        - Document length (numeric)
    date        - Document date ("yyyy-mm-dd hh:mm:ss.uuu")
    age         - Document age in milliseconds
    type        - Document type name (string)
    exists      - "Y" if the document exists, "N" otherwise
    directory   - "Y" if the document is a directory, "N" otherwise
    readable    - "Y" if the document is readable, "N" otherwise
    writable    - "Y" if the document is writable, "N" otherwise
 

Any name operand that is not one of the predefined names above is assumed to be an attribute that is specific to the implementation of the document class, and its value is retrieved using the DocumentI.getAttribute() method.

Other operands may be the following:

    number      - Numeric literal
    'string'    - Character string literal
    "string"    - Character string literal
 

A date-string is a quoted string containing the following components:

    yyyy-mm-dd hh:mm:ss.uuu     - Date/time literal

    yyyy    - Year
    mm      - Month
    dd      - Day of the month
    hh      - Hour
    mm      - Minute
    ss      - Second
    uuu     - Millisecond
 
Date/time components may be omitted on the right; any omitted components are assumed to match any value allowed. For example, the date value "2001-09-11 08" matches any date within the range 2001-09-11 08:00:00.000 to 2001-09-11 08:59:59.999.

A text-pattern is composed of normal characters and special pattern-matching characters, which are:

    _           - Matches any single character
    %           - Matches zero or more characters
    \x          - Removes the special meaning of x
 

A filename-pattern is composed of normal characters and special filename pattern-matching characters, which are:

    ?           - Matches any single character
    *           - Matches zero or more characters
    [abc]       - Matches a single character in the set {a,b,c}
    [a-z]       - Matches a single character in the range {a-z}
    [^a-z]      - Matches a single character not in the range {a-z}
    /           - Matches a directory path separator
    \x          - Removes the special meaning of x
 

Since:
2001-09-28
Version:
$Revision$ $Date$
Author:
David R. Tribble (david@tribble.com).
Copyright 2001 by David R. Tribble, all rights reserved.
See Also:
DocumentSearcherI, DocumentI, QueryParser, FilenamePattern

Field Summary
protected static java.lang.String ATTR_AGE
           
protected static java.lang.String ATTR_DATE
           
protected static java.lang.String ATTR_EXISTS
           
protected static java.lang.String ATTR_ISDIR
           
protected static java.lang.String ATTR_NAME
           
protected static java.lang.String ATTR_READ
           
protected static java.lang.String ATTR_SIZE
           
protected static java.lang.String ATTR_TYPE
           
protected static java.lang.String ATTR_WRITE
           
protected static java.lang.String[] ATTRIBUTES
           
protected  java.text.SimpleDateFormat m_dateFmt
          Date format specifier.
protected  QueryExpr m_expr
          Query expression tree.
protected  long m_now
          Current date/time (in milliseconds since 1970-01-01).
protected  java.lang.String m_query
          Query expression.
 
Fields inherited from interface tribble.search.DocumentFilterI
SERIES
 
Constructor Summary
DocumentQueryFilter(java.lang.String query)
          Constructor.
 
Method Summary
 boolean accept(DocumentI doc)
          Accept or reject a document entry.
protected  int compare(DocumentI doc, java.lang.String attr, java.lang.String lit)
          Compare a document attribute and a literal value.
protected  java.lang.String getDocumentAttribute(DocumentI doc, java.lang.String attr)
          Retrieve a named attribute for a document entry.
protected  boolean matches(DocumentI doc, QueryExpr query)
          Compare a document entry against a query expression.
protected  QueryExpr optimizeExpr(QueryExpr expr)
          Optimize a search query expression.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ATTR_NAME

protected static final java.lang.String ATTR_NAME
See Also:
Constant Field Values

ATTR_TYPE

protected static final java.lang.String ATTR_TYPE
See Also:
Constant Field Values

ATTR_SIZE

protected static final java.lang.String ATTR_SIZE
See Also:
Constant Field Values

ATTR_DATE

protected static final java.lang.String ATTR_DATE
See Also:
Constant Field Values

ATTR_AGE

protected static final java.lang.String ATTR_AGE
See Also:
Constant Field Values

ATTR_EXISTS

protected static final java.lang.String ATTR_EXISTS
See Also:
Constant Field Values

ATTR_ISDIR

protected static final java.lang.String ATTR_ISDIR
See Also:
Constant Field Values

ATTR_READ

protected static final java.lang.String ATTR_READ
See Also:
Constant Field Values

ATTR_WRITE

protected static final java.lang.String ATTR_WRITE
See Also:
Constant Field Values

ATTRIBUTES

protected static final java.lang.String[] ATTRIBUTES

m_query

protected java.lang.String m_query
Query expression.


m_expr

protected QueryExpr m_expr
Query expression tree.


m_dateFmt

protected java.text.SimpleDateFormat m_dateFmt
Date format specifier.


m_now

protected long m_now
Current date/time (in milliseconds since 1970-01-01).

Constructor Detail

DocumentQueryFilter

public DocumentQueryFilter(java.lang.String query)
                    throws java.text.ParseException
Constructor.

Parameters:
query - An SQL-like query expression, which specifies the criteria for accepting documents during a search operation. See the Query Syntax section for more details.
Throws:
java.text.ParseException - Thrown if the query expression is malformed.
Since:
1.1, 2001-09-28
See Also:
QueryExpr, QueryParser
Method Detail

accept

public boolean accept(DocumentI doc)
               throws java.lang.Exception
Accept or reject a document entry.

Specified by:
accept in interface DocumentFilterI
Parameters:
doc - A document entry.
Returns:
True if document entry doc is to be accepted, otherwise false if it is to be rejected.
Throws:
java.lang.Exception - Thrown if the selection criteria are malformed, or if some other error occurs.
Since:
1.1, 2001-09-28
See Also:
DocumentSearcherI.find(tribble.search.DocumentFilterI)

optimizeExpr

protected QueryExpr optimizeExpr(QueryExpr expr)
                          throws java.lang.Exception
Optimize a search query expression.

Parameters:
expr - A search query expression.
Returns:
An optimized equivalent of the original query expression.
Throws:
java.lang.Exception - Thrown if the selection criteria are malformed, or if some other error occurs.
Since:
1.1, 2001-10-10
See Also:
DocumentQueryFilter()

matches

protected boolean matches(DocumentI doc,
                          QueryExpr query)
                   throws java.lang.Exception
Compare a document entry against a query expression.

Parameters:
doc - A document entry.
query - A query expression tree.
Returns:
True if the document entry matches the query, otherwise false.
Throws:
java.lang.Exception - Thrown if the query criteria are malformed, or if some other error occurs.
Since:
1.1, 2001-09-28
See Also:
accept(tribble.search.DocumentI)

compare

protected int compare(DocumentI doc,
                      java.lang.String attr,
                      java.lang.String lit)
               throws java.lang.Exception
Compare a document attribute and a literal value.

Parameters:
doc - A document entry.
attr - The name of a document attribute (e.g., "name", "size", etc.) associated with it.
lit - Literal value to compare the document attribute to.
Returns:
A signed comparison result x, where:
x < 0 if attr is less than lit, or
x = 0 if attr is equal to lit, or
x > 0 if attr is greater than lit.
Throws:
java.lang.Exception - Thrown is the document does not have an attribute with the specified name, or if some other error occurs.
Since:
1.1, 2001-10-13

getDocumentAttribute

protected java.lang.String getDocumentAttribute(DocumentI doc,
                                                java.lang.String attr)
                                         throws java.lang.Exception
Retrieve a named attribute for a document entry.

Parameters:
doc - A document entry.
attr - The name of a document attribute (e.g., "name", "size", etc.) associated with it.
Returns:
The value of the document attribute, which may be empty ("").
Throws:
java.lang.Exception - Thrown is the document does not have an attribute with the specified name, or if some other error occurs.
Since:
1.1, 2001-09-28