001    package com.hammurapi.eventbus;
002    
003    import java.util.Collection;
004    
005    import com.hammurapi.common.ExceptionHandler;
006    import com.hammurapi.common.concurrent.AsynchronousProcessor;
007    import com.hammurapi.eventbus.Matcher.HandlerManager;
008    import com.hammurapi.extract.Predicate;
009    
010    /**
011     * Event bus asynchronously dispatches events to registered handlers.
012     * @author Pavel Vlasov
013     *
014     * @param <E> Event type.
015     * @param <P> Handler priority type.
016     * @param <C> Context type for extractors.
017     * @param <K> Event bus objects (handlers, events) ID type.
018     * @param <H> Handle type.
019     * @param <S> Event store type.
020     */
021    public interface EventBus<E, P extends Comparable<P>, C, K, H extends EventBus.Handle<E,P,C>, S extends EventStore<E,P,C,H,S>> extends AsynchronousProcessor {
022            
023            /**
024             * The primary purpose of Handle in the event bus is to be 
025             * a synchronization object. Its join() method blocks until all
026             * dispatching/inference associated with the posting of given 
027             * event is completed.
028             * @author Pavel Vlasov
029             *
030             */
031            interface Handle<E,P extends Comparable<P>,C> extends AsynchronousProcessor {
032                    
033                    E getEvent();
034                    
035                    /**
036                     * @return Derivations of this event.
037                     */
038                    Collection<Derivation<E,P,C>> getDerivations();
039                    
040                    /**
041                     * @return True if event is not consumed.
042                     */
043                    boolean isValid();
044                    
045                    boolean isDerivedFrom(E event);
046                    
047                    /**
048                     * Removes event from the bus.
049                     */
050                    void remove();
051                    
052                    /**
053                     * Informs the bus that the event was updated.
054                     */
055                    void update();                          
056                    
057            }
058            
059            Class<E> getEventType();
060            
061            InferencePolicy getInferencePolicy();
062    
063            void setExceptionHandler(ExceptionHandler exceptionHandler);
064    
065            ExceptionHandler getExceptionHandler();
066    
067            /**
068             * Registers event handler with a predicate.
069             * @param eventHandler Event handler.
070             * @param oneOff if true, event handler fires only once and the gets removed from the
071             * bus.
072             * @param predicate Predicates. The handler is invoked only if predicate evaluates to true. If there is more then one
073             * predicate, CommutativeAnd is constructed from predicates.
074             * @return Registration key object.
075             */
076            K addHandler(final EventHandler<E, P, C, H, S> eventHandler);
077    
078            /**
079             * Removes registered handler(s).
080             */
081            void removeHandlers(K... keys);
082            
083            /**
084             * Removes registered handler(s).
085             */
086            void removeHandlers(Iterable<K> keys);
087            
088            /**
089             * Posts event to the bus.
090             * @param event Event to dispatch to handlers.
091             * @param validators Predicate(s) which are checked when object is retrieved from the event store. 
092             * If there is more than one predicate, predicates are connected with AND. If validator(s) evaluate to
093             * false, the object handle is considered invalid, i.e. object is considered removed from the store. 
094             * Once validator(s) evaluate to false, they shall always evaluate to false. One of use of validators
095             * can be to expire object in the store, i.e. after some time validator returns false and object is cleared
096             * from the database. If validators evaluate to false at put time, object is not put to the store and 
097             * put() returns null. Validators evaluation result is not cached.
098             * @return Event handle or null if validator(s) evaluate to false. 
099             */
100            H post(E event, Predicate<E, S>... validators);
101    
102            /**
103             * Clears join collections and handle map.
104             */
105            void reset();
106    
107            /**
108             * @param event
109             * @return Derivations for the event.
110             */
111            Collection<Derivation<E,P,C>> getDerivations(E event);
112            
113            /**
114             * @return event store.
115             */
116            S getStore();
117            
118            /**
119             * Removes event from the bus.
120             * @param event
121             */
122            void remove(E event);
123                    
124            /**
125             * This method is used for batch live updates of bus handlers.
126             * The method acquires bus write lock, then invokes bus manager's manageBus() method within a lock
127             * and then releases the lock. Therefore, event bus structure update is executed as one logical unit. 
128             * @param busManager
129             */
130            void manageHandlers(HandlerManager<E,P,C,K,H,S> handlerManager);
131            
132    }