TapFilter.mesa
Copyright Ó 1989 by Xerox Corporation. All rights reserved.
Doug Terry, February 27, 1990 4:05:01 pm PST
Facilities for filtering and annotating documents.
Brian Oki, March 3, 1991 1:18 pm PST
Sabel, July 30, 1990 4:11 pm PDT
DIRECTORY
LoganBerry USING [Entry],
Rope USING [ROPE],
TapMsgQueue USING [Msg, MsgQueue]
;
TapFilter: CEDAR DEFINITIONS
~
BEGIN
ROPE: TYPE ~ Rope.ROPE;
Msg: TYPE ~ TapMsgQueue.Msg;
MsgQueue: TYPE ~ TapMsgQueue.MsgQueue;
Annotation: TYPE ~ LoganBerry.Entry;
Query: TYPE ~ ROPE;
Agent: TYPE ~ REF;
Any procedure defined below may raise the following error:
Error: ERROR [ec: ATOM, explanation: ROPE ← NIL];
FilterInfo: TYPE ~ RECORD[filterName, user: ROPE, query: Query, annot: Annotation];
Agents
Agents process a queue of messages by running them through a set of filters. If a message "passes" a particular filter, then the annotation associated with that filter is attached to the message. Once an agent is created, it exists until it is terminated. When an agent discovers that there are no more messages to be processed, it goes to sleep, i.e. into the idle state. An agent may periodically wakeup and look for more messages or it may be explicitly awaken.
CreateAgent:
PROC [feeder: MsgQueue, filterDB:
ROPE, user:
ROPE, annotDB:
ROPE]
RETURNS [agent: Agent];
Creates a filtering agent for the particular user. This agent reads messages from the feeder message queue. The set of filters are obtained from the given filterDB, while any generated annotations are written to the given annotDB.
WakeupAgent:
PROC [agent: Agent]
RETURNS [];
Prod the given agent to start processing messages. This may not be necessary, but is always a good thing to do after adding messages to the agent's feeder queue.
IsAgentIdle:
PROC [agent: Agent, wait:
BOOLEAN ←
FALSE]
RETURNS [idle:
BOOLEAN];
Checks if the given agent is currently idle. If wait=TRUE then the procedure blocks until it can return idle=TRUE.
MonitorProc: TYPE ~ PROC [msgID: ROPE, msg: Msg, filterID: ROPE, annot: Annotation] RETURNS [doIt: BOOLEAN ← TRUE];
MonitorAgent:
PROC [agent: Agent, proc: MonitorProc]
RETURNS [];
The given MonitorProc is called by the given agent whenever it is about to add an annotation to the database. The MonitorProc is passed information about the message being annotated, the filter that selected that message, and the annotation itself. If the MonitorProc returns doIt=FALSE then the annotation is not added, otherwise it proceeds as planned.
TerminateAgent:
PROC [agent: Agent]
RETURNS [];
Halts and destroys the given agent.
Filters
Filters are associated with particular users and stored in a database.
AddFilter:
PROC [filterDB:
ROPE, user:
ROPE, filterName:
ROPE, query: Query, annot: Annotation, agent: Agent ←
NIL]
RETURNS [filterID:
ROPE];
Adds a new filter. If agent#NIL then the given agent immediately starts using the new filter.
DeleteFilter:
PROC [filterDB:
ROPE, filterID:
ROPE, agent: Agent ←
NIL]
RETURNS [];
Removes the given filter. If agent#NIL then the given agent stops using the specified filter.
LookupFilter:
PROC [filterDB:
ROPE, filterID:
ROPE]
RETURNS [filterName, user:
ROPE, query: Query, annot: Annotation];
Returns information about the given filter. If filterName is NIL, then no such filter exists.
LookupAllFilters:
PROC [filterDB:
ROPE]
RETURNS [
LIST
OF FilterInfo];
Returns information about all filters.
ExistsFilter:
PROC [filterDB:
ROPE, filterID:
ROPE]
RETURNS [
BOOLEAN];
Annotations
Annotations are associated with particular messages and stored in a database.
AnnotateMsg:
PROC [annotDB:
ROPE, msgID:
ROPE, filterID:
ROPE, annot: Annotation]
RETURNS [annotID:
ROPE];
Adds an annotation for the given message.
GetAnnotations:
PROC [annotDB:
ROPE, msgID:
ROPE]
RETURNS [annot: Annotation];
Returns all annotations for the given message.
Utilities
ParseMsgIntoFields:
PROC [msgtext:
ROPE]
RETURNS [msg: Msg];
Takes a textual message and parses it into a list of fields and values. A field is some text of the form "field: value". Text that cannot be parsed into fields is returned as a field of type $text.
END.