001/*
002 * Copyright (c) 2006-2013 Nuxeo SA (http://nuxeo.com/) and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Bogdan Stefanescu
011 *     Florent Guillaume
012 */
013package org.nuxeo.ecm.core.event;
014
015import java.util.List;
016
017import org.nuxeo.ecm.core.event.impl.EventListenerDescriptor;
018
019/**
020 * The event service manages listener registries and notifies listeners about core events.
021 * <p>
022 * The service is able to run in a transactional mode where all events are recorded and fired after the transaction
023 * commits in one step as an event bundle.
024 * <p>
025 * To start a transaction, the framework calls the {@link #transactionStarted()} method, and at transaction commit the
026 * framework calls {@link #transactionCommitted()} to fire the event bundle. Upon rollback the framework calls
027 * {@link #transactionRolledback()} to clean up recorded events.
028 * <p>
029 * Events are recorded in a thread variable so they are valid only in the current thread.
030 * <p>
031 * An event marked {@link Event#isInline()} is dispatched immediately, otherwise it is recorded in a thread-based bundle
032 * of current events. If no transaction was started, an event marked {@link Event#isCommitEvent()} is used to flush the
033 * event bundle to its listeners, otherwise the transaction commit does the flush.
034 * <p>
035 * Listeners are of two types: {@link EventListener} notified as the event is raised and {@link PostCommitEventListener}
036 * notified after the transaction was committed.
037 */
038public interface EventService extends EventProducer {
039
040    /**
041     * Adds a new event listener. Used by the framework.
042     * <p>
043     * The event listener is described by a {@link EventListenerDescriptor} that may specify a priority. Both types of
044     * listeners (immediate and post-commit) are registered.
045     *
046     * @param listener the listener to add
047     */
048    void addEventListener(EventListenerDescriptor listener);
049
050    /**
051     * Removes an event listener. Used by the framework.
052     *
053     * @param listener the listener to remove
054     */
055    void removeEventListener(EventListenerDescriptor listener);
056
057    /**
058     * Fires an event given its name and a context.
059     *
060     * @param name the event name
061     * @param context the event context
062     */
063    void fireEvent(String name, EventContext context);
064
065    /**
066     * Fires an event.
067     * <p>
068     * If a transaction was started, the event is registered if needed to be sent after the transaction commit.
069     *
070     * @param event the event to fire
071     */
072    @Override
073    void fireEvent(Event event);
074
075    /**
076     * Fires all recorded events in a transaction. Used by the framework.
077     * <p>
078     * The events are fired to {@link PostCommitEventListener} listeners. Events are fired in the form of an event
079     * bundle.
080     *
081     * @param event the event bundle
082     */
083    @Override
084    void fireEventBundle(EventBundle event);
085
086    /**
087     * Fires an event bundle in synchronous mode. Used by the framework.
088     * <p>
089     * This means that asynchronous listeners will be run synchronously.
090     */
091    void fireEventBundleSync(EventBundle event);
092
093    /**
094     * Gets the list of the registered event listeners.
095     * <p>
096     * Modification on this list will not modify the internal lists in this {@link EventService}.
097     *
098     * @return the event listeners
099     */
100    List<EventListener> getEventListeners();
101
102    /**
103     * Get the list of the registered post commit event listeners.
104     * <p>
105     * Modification on this list will not modify the internal lists in this {@link EventService}.
106     *
107     * @return the post commit event listeners
108     */
109    List<PostCommitEventListener> getPostCommitEventListeners();
110
111    /**
112     * Gets the event listener descriptor corresponding to the give name.
113     *
114     * @since 5.8
115     * @param name the event listener name
116     * @return the descriptor, or {@code null} if not found
117     */
118    EventListenerDescriptor getEventListener(String name);
119
120    /**
121     * Waits until all asynchronous tasks are finished.
122     */
123    void waitForAsyncCompletion();
124
125    /**
126     * Waits until all asynchronous tasks are finished, but waits no longer than the given number of milliseconds.
127     *
128     * @param timeout the maximum time to wait for, in milliseconds
129     */
130    void waitForAsyncCompletion(long timeout);
131
132}