1.1 --- a/BLIP/BLIPDispatcher.h Fri May 23 17:37:36 2008 -0700
1.2 +++ b/BLIP/BLIPDispatcher.h Sun May 25 13:43:03 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