Class Selector.

Inherits Garbage

This class represents a set of conditions to select messages from a mailbox.

The Selector class represents a single condition in a search, which is either a leaf condition or an AND/OR operator.

The class can simplify() and regularize itself, such that all equivalent search inputs give the same result, and and it can express itself in a form amenable to testing. Rather simple.

Selector::Selector( Action a )

Creates a selector with Action a.

Selector::Selector( Field f )

Constructs an empty selector with field f and Action Special.

Selector::Selector( Field f, Action a, const EString & s )

Creates a selector with Field f, Action a, and the string value s.

Selector::Selector( Field f, Action a, const EString & s, const EString & t, const UString & u )

Creates a selector with Field f, Action a, the EString values s and t, and the UString value u.

Selector::Selector( Field f, Action a, const EString & s, const UString & u )

Creates a selector with Field f, Action a, the EString value s, and the UString value u.

Selector::Selector( Field f, Action a, const UString & u )

Creates a selector with Field f, Action a, and the UString value u.

Selector::Selector( Field f, Action a, uint n )

Creates a selector with Field f, Action a, and the integer value n.

Selector::Selector( Mailbox * mailbox, bool alsoChildren )

Constructs a selector that matches messages in mailbox and if alsoChildren is true, also in its children.

Selector::Selector( const IntegerSet & s )

Creates a selector from the IntegerSet s.

Selector::Selector()

Creates a new root "And" selector.

Reimplements Garbage::Garbage().

Action Selector::action() const

Returns the action specified using the constructor.

void Selector::add( Selector * s )

Adds the Selector s to the list of this Selector's children.

bool Selector::alsoChildren() const

Returns true if this selector should match messages in children of mailbox(), and false if not.

List<Selector> * Selector::children()

Returns a pointer to this selector's children (only applicable for and/or/not selectors). May return a pointer to an empty list, but will never return a null pointer.

EString Selector::debugString() const

Give an ASCII representatation of this object, suitable for debug output or for equality testing.

bool Selector::dynamic() const

Returns true if this Selector includes at least one dynamic message attribute (something which can change after message arrival). If dynamic(), then repeating the Selector's query() can yield different results. (That is of course the very subject of RFC 4551.)

EString Selector::error()

Returns the first error recorded with setError, or an empty string if none has been recorded yet.

Field Selector::field() const

Returns the field specific using the constructor.

static Selector * Selector::fromString( const EString & s )

This static function takes a canonical string representation s, and returns the Selector corresponding to it, or 0 if there was a parsing error.

int Selector::integerArgument() const

Returns the numeric argument supplied to some constructors, or 0 if none has been specified.

Mailbox * Selector::mailbox() const

Returns a pointer to the mailbox on which this selector operates.

MatchResult Selector::match( Session * s, uint uid )

Matches the message with the given uid in the session s against this condition, provided the match is reasonably simple and quick, and returns either Yes, No, or (if the match is difficult, expensive or depends on data that isn't available) Punt.

const IntegerSet & Selector::messageSet() const

Returns a reference to the set passed to the constructor. If the constructor didn't accept a set, messageSet() returns a reference to an empty set.

IntegerSet Selector::messageSetArgument() const

Returns the message set supplied to some constructors, or an empty set if none has been specified.

EString Selector::mm()

Returns a string such as "mm", referring to the mailbox_messages table. This may also be "dm", "dm2", "mm42" or worse, if the search is really complex.

bool Selector::needSession() const

Returns true if this condition needs an updated Session to be correctly evaluated, and false if not.

Selector * Selector::parent()

Returns the parent of this Selector, or 0 if it is the root.

uint Selector::placeHolder( const EString & s )

Returns a placeholder bound to s, creating one if necessary.

uint Selector::placeHolder( const UString & s )

Returns a placeholder bound to s, creating one if necessary.

uint Selector::placeHolder()

Returns the next integer from a monotonically increasing sequence on each call. The first value is 1. (This is used to construct the $n placeholder names in queries.)

Query * Selector::query( User * user, Mailbox * mailbox, Session * session, EventHandler * owner, bool order, EStringList * wanted, bool deleted )

Returns a query representing this Selector or 0 if anything goes wrong, in which case error() contains a description of the problem. The Selector is expressed as SQL in the context of the specified user and session. The owner will be notified of query results.

The mailbox to search is passed in separately, because we can't use the Session's mailbox while building views. If mailbox is a null pointer, the query will search either the entire database or the part that's visible to user.

If deleted is supplied and true (the default is false), then the Query looks at the deleted_messages table instead of the mailbox_messages one.

The search results will be ordered if order is true (this is the default). The order is ascending and uses whatever is specified in wanted of mailbox, uid, message and idate.

Each Query Row will have the result columns named in wanted, or "uid", "modseq" and "message" if wanted is left at the default value.

Selector * Selector::root()

Returns the ultimate parent of this Selector.

void Selector::setError( const EString & s )

Records s as an error during the construction of this Selector tree. Only the first error in a tree is recorded, and it is recorded at the root of the tree (rather than the node where it occurred).

static void Selector::setup()

Performs whatever duties the Selector needs to have performed at startup. Selector can be used even without calling setup().

void Selector::simplify()

This helper transforms this search conditions and all its children into a simpler form, if possible. There are three goals to this:

1. Provide a regular search expression, so that we can eventually detect and prepare statements for often-repeated searches.

2. Ditto, so that we can test that equivalent input gives identical output.

3. Avoid search expressions which would be horribly inefficient or just plain impossible for the RDBMS.

EString Selector::string()

Returns the string representation of this Selector. This is what's stored in the views.selector column in the database.

EString Selector::stringArgument() const

Returns the 8-bit string supplied to some constructors, or an empty string if none has been specified.

bool Selector::timeSensitive() const

Returns true if this Selector includes at least one time-sensitive message attribute (something which can change as time passes). If the Selector is timeSensitive(), it is also dynamic().

bool Selector::usesModseq() const

Returns true if this Selector includes modseq logic, and false if not.

UString Selector::ustringArgument() const

Returns the unicode string supplied to some constructors, or an empty string if none has been specified.

EString Selector::where()

Gives an SQL string representing this condition.

The string may include $n placeholders; where() and its helpers will bind them as required.

EString Selector::whereAddressField()

This implements searches on a single address field, or on all address fields if stringArgument() is empty.

EString Selector::whereAddressFields( List<Selector> * fields )

This implements searching for the given address fields, or on all address fields if fields is the empty list.

XXX: This comment may be wrong.

EString Selector::whereAge()

This implements the older/younger search-keys.

EString Selector::whereAnnotation()

This implements searches on whether a message has/does not have the right annotation.

EString Selector::whereBody()

This implements searches on (text) bodyparts. We cannot and will not do "full-text" search on the contents of e.g. jpeg pictures. (For some formats we search on the text part, because the injector sets bodyparts.text based on bodyparts.data.)

This function uses full-text search if available, but filters the results with a plain 'ilike' in order to avoid overly liberal stemming. (Perhaps we actually want liberal stemming. I don't know. IMAP says not to do it, but do we listen?)

EString Selector::whereFlags()

This implements searches on whether a message has/does not have flags.

EString Selector::whereHeader()

This implements searches on all header fields.

EString Selector::whereHeaderField()

This implements searches on a single header field.

EString Selector::whereHeaders( List<Selector> * sl )

This helper helps the OR optimiser in whereNoField() to search for any of a set of headers or header fields, disregarding address fields.

sl must be a non-null pointer to a nonempty list of headers or header fields.

EString Selector::whereInThread()

This implements inthread, that is, a thread-specific search.

Conceptually simple but perhaps a little hard on the RDBMS.

EString Selector::whereInternalDate()

This implements the INTERNALDATE part of where().

EString Selector::whereMailbox()

This implements a search that's bound to a specific mailbox or a subtree.

This does no permission checking. query() includes a gargantuan clause to limit the search to mailboxes the user can read; this function relies on that clause.

EString Selector::whereModseq()

This implements the modseq search-key.

EString Selector::whereNoField()

This implements any search that's not bound to a specific field, generally booleans and "all".

As a hack, oops, as an optimization, this function also looks for an OR list of address-field searches, and if any, lifts the shared parts of those searches out so the DBMS processes the search faster.

EString Selector::whereRfc822Size()

This implements searches on the rfc822size of messages.

EString Selector::whereSent()

This implements the SENTON/SENTBEFORE/SENTSINCE part of where().

EString Selector::whereSet( const IntegerSet & s )

Returns a condition to match the numbers in s. Binds 0-2 variables.

EString Selector::whereUid()

This implements searches on whether a message has the right UID.

This web page based on source code belonging to The Archiveopteryx Developers. All rights reserved.