tribble.search
Class DocumentQueryFilter

java.lang.Object
  tribble.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