1.1 --- a/BLIP/BLIPDispatcher.h	Fri May 23 17:37:36 2008 -0700
     1.2 +++ b/BLIP/BLIPDispatcher.h	Sun May 25 12:33:50 2008 -0700
     1.3 @@ -10,19 +10,48 @@
     1.4  @class MYTarget, BLIPMessage;
     1.5  
     1.6  
     1.7 +/** Routes BLIP messages to targets based on a series of rule predicates.
     1.8 +    Every BLIPConnection has a BLIPDispatcher, which is initially empty but you can add rules
     1.9 +    to it.
    1.10 + 
    1.11 +    Every BLIPListener also has a dispatcher, which is inherited as the parent by every
    1.12 +    connection that it accepts, so you can add rules to the listener's dispatcher to share them
    1.13 +    between all connections.
    1.14 + 
    1.15 +    It's not necessary to use a dispatcher. Any undispatched requests will be sent to the
    1.16 +    BLIPConnection's delegate's -connection:receivedRequest: method, which can do its own
    1.17 +    custom handling. But it's often easier to use the dispatcher to associate handlers with
    1.18 +    request based on property values. */
    1.19  @interface BLIPDispatcher : NSObject 
    1.20  {
    1.21      NSMutableArray *_predicates, *_targets;
    1.22      BLIPDispatcher *_parent;
    1.23  }
    1.24  
    1.25 +/** The inherited parent dispatcher.
    1.26 +    If a message does not match any of this dispatcher's rules, it will next be passed to
    1.27 +    the parent, if there is one. */
    1.28  @property (retain) BLIPDispatcher *parent;
    1.29  
    1.30 +/** Adds a new rule, to call a given target method if a given predicate matches the message. */
    1.31  - (void) addTarget: (MYTarget*)target forPredicate: (NSPredicate*)predicate;
    1.32 +
    1.33 +/** Convenience method that adds a rule that compares a property against a string. */
    1.34 +- (void) addTarget: (MYTarget*)target forValueOfProperty: (NSString*)value forKey: (NSString*)key;
    1.35 +
    1.36 +/** Removes all rules with the given target method. */
    1.37  - (void) removeTarget: (MYTarget*)target;
    1.38  
    1.39 -- (void) addTarget: (MYTarget*)target forValueOfProperty: (NSString*)value forKey: (NSString*)key;
    1.40 -
    1.41 +/** Tests the message against all the rules, in the order they were added, and calls the
    1.42 +    target of the first matching rule.
    1.43 +    If no rule matches, the message is passed to the parent dispatcher's -dispatchMessage:,
    1.44 +    if there is a parent.
    1.45 +    If no rules at all match, NO is returned. */
    1.46  - (BOOL) dispatchMessage: (BLIPMessage*)message;
    1.47  
    1.48 +/** Returns a target object that will call this dispatcher's -dispatchMessage: method.
    1.49 +    This can be used to make this dispatcher the target of another dispatcher's rule,
    1.50 +    stringing them together hierarchically. */
    1.51 +- (MYTarget*) asTarget;
    1.52 +
    1.53  @end