    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    }