Filter Expressions
Grace Software
JavaLog

$Revision: 1.1 $
$Date: 2000/02/02 14:34:23 $

Introduction

The old style filtering in JavaLog provides global filtering for events. In other words, all events logged were passed through a very simple filter mechanism before being dispatched to the Handlers. Version 0.8 introduces a more flexible system of filtering that allows the user to specify runtime expressions that filter events globaly on for a specific handler.

The transition to this expression based filtering may span multiple JavaLog releases. Currently, the per handler filtering is implemented but the global filtering may not make it to the current release.

Note, this functionality is currently experimental and evolving so be patient. Only part of this functionality is currently working. The rest of this document may describe functionality that is not currently implemented.

Runtime

To specify a runtime filter for a handler, specify the ".filter" property for that handler, as follows: 
    $ java -Dlog.handler.out.filter=filter-expression MyClass
When the filter property is specified, a special FilterQueueHandler is installed as a filter before the specified handler. So, events that pass the given filter-expression are then passed to the actual requested handler.

Syntax

Filters are expressions that look like to terse java expressions. Here's a loose pattern for the format of these expressions. 
    expr:		op-expr | or-expr | and-expr | sub-expr | not-expr
    or-expr:		expr '|' expr
    and-expr:		expr '&' expr
    sub-expr:		'(' expr ')'
    unary-expr:		unary-operator expr
    binary-expr:		name binary-operator value

    binary-operator:	'=' | '~' | '>' | '<'
    unary-opertor:	'!'

    name:		function              # concated class.function
                        | type                # error, warning, trace, etc.
			| line		      # line number
			| message
			| object.type
			| object.name
			| exception.message
    value:		string | integer

For example:

    $ java -Dlog.handler.out.filter=
        "(type=error | type=warning) & function ~ grace.log.*" MyClass
This expression will filter the standard out so only errors and warnings from the grace.log package would be logged to standard output. Note that all whitespace is ignored.

Equals

An expression like "type = error" means that a tested event have the exact type of "error" to pass this expression.

Like

The patten "name ~ regular-expression/" allows inexact comparison expressions. For example, "function ~ grace.log.*" specifies an expression that would include all of the functions that match the regular expression pattern. So here, all the functions in the grace.log package will be logged.

Not

Any operator can be prefixed by '!' to invert the logic for that operator.

Less than and greater than

For integer right hand values like line number, the '<' and '>' operators allows integer limit comparisons.