The framework in base/sequencer.cls was written to ease the generation of command/response chains usually required during implementation of a client for various internet protocols (smtp, pop3, ...). It cuts down the size of redundantly written code too.
To use the framework one has to derive a class from sequencer and overide some methods.
Examples of its usage can be found in the net/pop3 and net/smtp directories. More concrete: pop3Sequencer and pop3RetrSeq.
The framework knows the events 'done', 'eof', 'error', 'line', 'next' and 'timeout'. They can be raised from the outside or the sequencer itself, through calling sequencer:event. An important thing to remember, in the calling context sequencer:event will act like a 'return' statement.
Of these six events only two, 'error' and 'line', accept a single argument, which will be interpreted as the error message, resp. the incoming line to handle.
The actions executed upon receiving an event are as follows.
| Event | Action | |
|---|---|---|
| Common (to all) | The raised event is stored in the membervariable sequencer:state. | |
| done | Calls the abstract method sequencer:OnDone first, then destroys the sequencer object. The derived class has to overide this method to do something useful, like notifying the environment about the impeding destruction. As event (and possibly an error message) are stored in the object before doing this the derived is able to act differently, based on the exact cause of the desctruction. | |
| eof | The same as for 'done'. | |
| error | The same as for 'done', with one exception. The first argument after the event is interpreted as the error message and stuffed into the membervariable sequencer:error. | |
| line |
Calls the method sequencer:OnLine. The first argument
behind the event is forwarded to the method. Errors during its
execution are handled by raising an 'error' event. The implementation
provided in this class uses the member variable
sequencer:lineMethod to dynamically call a method of the
derived class. The 'line' argument is forwarded to the invoked method.
The method sequencer:wait should be used to define its
contents. Derived classes are allowed to overide
sequencer:OnLine. sequencer:wait actually does more than simply setting up sequencer:lineMethod. It additionally places a read fileevent handler on the channel given to it and start a timer which will time out after sequencer:timeout milliseconds, causing a 'timeout' to be raised. On the other hand, activity on the channel causes a line to be read and then send to ourselves through a 'line' event. If the channel was closed 'eof' is raised. Whatever happened, the timer is cancelled. The callback methods are sequencer:Timeout and sequencer:Receive. |
|
| next | Calls the method sequencer:OnNext. Errors during its execution are handled by raising an 'error' event. The implementation provided in this class uses the member variable sequencer:nextMethod to dynamically call a method of the derived class. The method sequencer:next should be used to define its contents. Derived classes are allowed to overide sequencer:OnNext. | |
| timeout | The same as for 'done'. |
Generated by AutoDoc 2.4 at 09/14/2000, invoked by Andreas Kupries