ostore.dispatch
Class Resender

java.lang.Object
  |
  +--ostore.dispatch.Resender

public class Resender
extends Object

A utility class that automatically re-dispatches events.

If an attempt to dispatch an event throws a SinkFullException, the Resender schedules the event for a later attempt and returns a unique, opaque token. That token can be used later to confirm or cancel delivery.

NOTE: A Resender does not guarantee any delivery order for events which are initially delayed. If in-order delivery is important, do not use the automatic re-dispatching features, or avoid this class completely.

Any stage which uses a Resender must Signal.register(int, java.lang.String, mdw.sandStorm.api.SinkIF) for Signal.ALRM signals targetted at the name given to the Resender constructor. The Resender will set its own alarms; the stage must catch the resulting AlarmSignals and call process_queues().

Version:
$Id: Resender.java,v 1.2 2002/02/15 20:41:19 geels Exp $
Author:
Dennis Geels

Constructor Summary
Resender(NodeId node_id, String stage_name)
          Creates a new Resender object that uses the default Classifier for the specified machine.
 
Method Summary
 boolean cancel(Object token)
          Cancels the specified event.
 QueueElementIF[] clear(boolean all)
          Cancels all events which have timed out.
 Object dispatch(QueueElementIF event)
          Dispatches an event through the Classifier.
 Object dispatch(QueueElementIF event, int num_retries, long millis)
          Dispatch the specified event, making at most num_retries additional attempts, waiting millis milliseconds in between attempts.
 boolean pending(Object token)
          Checks whether the specified event is scheduled for further attempts.
 void process_queues()
          Processes the queue of pending events, sending any whose deadlines have been reaced.
 boolean timed_out(Object token)
          Checks whether the specified event was been successfully dispatched.
 boolean was_sent(Object token)
          Checks whether the specified event has been successfully dispatched.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Resender

public Resender(NodeId node_id,
                String stage_name)
Creates a new Resender object that uses the default Classifier for the specified machine.
Parameters:
node_id - The ID for this machine - needed to locate the correct Classifier and Signal.
stage_name - The name of the calling stage - needed to address AlarmSignals properly.
Method Detail

process_queues

public void process_queues()
Processes the queue of pending events, sending any whose deadlines have been reaced.

This method should be called each time the stage receives an AlarmSignal.


dispatch

public Object dispatch(QueueElementIF event)
Dispatches an event through the Classifier.

If the dispatch fails, the event is stored in a trash pile. Events on the trash pile can be recovered by the clear(boolean) method.

Parameters:
event - Any event to dispatch
Returns:
a token, used to reference the event later, or null if the object was successfully dispatched.
See Also:
dispatch(mdw.sandStorm.api.QueueElementIF, int, long), Classifier.dispatch(mdw.sandStorm.api.QueueElementIF)

dispatch

public Object dispatch(QueueElementIF event,
                       int num_retries,
                       long millis)
Dispatch the specified event, making at most num_retries additional attempts, waiting millis milliseconds in between attempts.

After enough attempts have failed, the event is stored in a trash pile. Events on the trash pile can be recovered by the clear(boolean) method.

Parameters:
event - Any event to dispatch
num_retries - The number (>=0) of times to try dispatching the event if the initial attempt fails.
millis - The number of milliseconds to wait after each attempt.
Returns:
a token, used to reference the event later, or null if the object was successfully dispatched on the first try.
See Also:
dispatch(mdw.sandStorm.api.QueueElementIF), Classifier.dispatch(mdw.sandStorm.api.QueueElementIF)

cancel

public boolean cancel(Object token)
Cancels the specified event. All state relating to the pending event is removed from the Resender. If the event has already dispatched successfully, this method does nothing.
Parameters:
token - A token returned by dispatch(mdw.sandStorm.api.QueueElementIF).
Returns:
true iff the event has not yet been dispatched successfully.
See Also:
dispatch(mdw.sandStorm.api.QueueElementIF, int, long)

timed_out

public boolean timed_out(Object token)
Checks whether the specified event was been successfully dispatched.
Parameters:
token - A token returned by dispatch(mdw.sandStorm.api.QueueElementIF).
Returns:
true iff the event has timed out.
See Also:
dispatch(mdw.sandStorm.api.QueueElementIF, int, long)

pending

public boolean pending(Object token)
Checks whether the specified event is scheduled for further attempts.
Parameters:
token - A token returned by dispatch(mdw.sandStorm.api.QueueElementIF).
Returns:
true iff the event is on the queue for another attempted dispatch.
See Also:
dispatch(mdw.sandStorm.api.QueueElementIF, int, long)

was_sent

public boolean was_sent(Object token)
Checks whether the specified event has been successfully dispatched.

Equivalent to ( !pending(token) && !timed_out(token) ).

Parameters:
token - A token returned by dispatch(mdw.sandStorm.api.QueueElementIF).
Returns:
true iff the Resender no longer has any memory of the token, which implies that the event was previously dispatched.
See Also:
dispatch(mdw.sandStorm.api.QueueElementIF, int, long)

clear

public QueueElementIF[] clear(boolean all)
Cancels all events which have timed out. If all == true, also cancels all pending events.
Parameters:
all - true iff pending events should also be cancelled.
Returns:
an array containing all cancelled events.
See Also:
dispatch(mdw.sandStorm.api.QueueElementIF, int, long), cancel(java.lang.Object)