jens@0: //
jens@0: //  BLIPDispatcher.h
jens@0: //  MYNetwork
jens@0: //
jens@0: //  Created by Jens Alfke on 5/15/08.
jens@0: //  Copyright 2008 Jens Alfke. All rights reserved.
jens@0: //
jens@0: 
jens@0: #import <Foundation/Foundation.h>
jens@0: @class MYTarget, BLIPMessage;
jens@0: 
jens@0: 
jens@2: /** Routes BLIP messages to targets based on a series of rule predicates.
jens@2:     Every BLIPConnection has a BLIPDispatcher, which is initially empty but you can add rules
jens@2:     to it.
jens@2:  
jens@2:     Every BLIPListener also has a dispatcher, which is inherited as the parent by every
jens@2:     connection that it accepts, so you can add rules to the listener's dispatcher to share them
jens@2:     between all connections.
jens@2:  
jens@2:     It's not necessary to use a dispatcher. Any undispatched requests will be sent to the
jens@2:     BLIPConnection's delegate's -connection:receivedRequest: method, which can do its own
jens@2:     custom handling. But it's often easier to use the dispatcher to associate handlers with
jens@2:     request based on property values. */
jens@0: @interface BLIPDispatcher : NSObject 
jens@0: {
jens@0:     NSMutableArray *_predicates, *_targets;
jens@0:     BLIPDispatcher *_parent;
jens@0: }
jens@0: 
jens@2: /** The inherited parent dispatcher.
jens@2:     If a message does not match any of this dispatcher's rules, it will next be passed to
jens@2:     the parent, if there is one. */
jens@0: @property (retain) BLIPDispatcher *parent;
jens@0: 
jens@2: /** Adds a new rule, to call a given target method if a given predicate matches the message. */
jens@0: - (void) addTarget: (MYTarget*)target forPredicate: (NSPredicate*)predicate;
jens@2: 
jens@2: /** Convenience method that adds a rule that compares a property against a string. */
jens@2: - (void) addTarget: (MYTarget*)target forValueOfProperty: (NSString*)value forKey: (NSString*)key;
jens@2: 
jens@2: /** Removes all rules with the given target method. */
jens@0: - (void) removeTarget: (MYTarget*)target;
jens@0: 
jens@2: /** Tests the message against all the rules, in the order they were added, and calls the
jens@2:     target of the first matching rule.
jens@2:     If no rule matches, the message is passed to the parent dispatcher's -dispatchMessage:,
jens@2:     if there is a parent.
jens@2:     If no rules at all match, NO is returned. */
jens@0: - (BOOL) dispatchMessage: (BLIPMessage*)message;
jens@0: 
jens@2: /** Returns a target object that will call this dispatcher's -dispatchMessage: method.
jens@2:     This can be used to make this dispatcher the target of another dispatcher's rule,
jens@2:     stringing them together hierarchically. */
jens@2: - (MYTarget*) asTarget;
jens@2: 
jens@0: @end