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