001    package com.hammurapi.eventbus;
002    
003    import java.util.concurrent.ExecutorService;
004    
005    import com.hammurapi.eventbus.AbstractEventBus.Snapshot;
006    
007    /**
008     * Implementations of this interface match handlers to events.
009     * @author Pavel Vlasov
010     *
011     */
012    public interface Matcher<E, P extends Comparable<P>, C, K, H extends EventBus.Handle<E,P,C>, S extends EventStore<E,P,C,H,S>> {
013            
014            /**
015             * Adds handler to the matcher.
016             * @param eventHandler
017             * @return
018             */
019            K addHandler(final EventHandler<E, P, C, H, S> eventHandler);     
020    
021            /**
022             * @param event
023             * @param executorService Executor service to use for parallel matching.
024             * @return Handlers matching the event ordered by priority.
025             */
026            Iterable<EventHandlerWrapper<E, P, C, K, H, S>> match(E event, ExecutorService executorService);
027            
028            /**
029             * Takes matcher snapshot.
030             * @param snapshot
031             */
032            void takeSnapshot(Snapshot<E, P, C, K, H, S> snapshot);
033    
034            void removeHandlers(Iterable<K> keys);
035    
036            /**
037             * Resets handler's state.
038             */
039            void reset();
040            
041            /**
042             * Interface for live batch update of handlers.
043             * @author Pavel Vlasov
044             *
045             * @param <E>
046             * @param <P>
047             * @param <C>
048             * @param <K>
049             * @param <H>
050             */
051            interface HandlerManager<E, P extends Comparable<P>, C, K, H extends EventBus.Handle<E,P,C>, S extends EventStore<E,P,C,H,S>> {         
052                    void manageHandlers(Matcher<E,P,C,K,H,S> matcher);                
053            }
054            
055            /**
056             * This method is used for batch live updates of matcher handlers.
057             * The method acquires matcher write lock, then invokes matcher manager's manageHandlers() method within the lock
058             * and then releases the lock. Therefore, matcher structure update is executed as one logical unit. 
059             * @param handlerManager
060             */
061            void manageHandlers(HandlerManager<E,P,C,K,H,S> handlerManager);
062            
063            /**
064             * This method is invoked by the bus to provide a reference to self.
065             * @param bus
066             */
067            void setEventBus(EventBus<E,P,C,K,H,S> bus);
068    }