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;
025import org.nuxeo.ecm.core.event.stream.DomainEventProducer;
026
027/**
028 * The event service manages listener registries and notifies listeners about core events.
029 * <p>
030 * The service is able to run in a transactional mode where all events are recorded and fired after the transaction
031 * commits in one step as an event bundle.
032 * <p>
033 * To start a transaction, the framework calls the {@code transactionStarted()} method, and at transaction commit the
034 * framework calls {@code transactionCommitted()} to fire the event bundle. Upon rollback the framework calls
035 * {@code transactionRolledback()} to clean up recorded events.
036 * <p>
037 * Events are recorded in a thread variable so they are valid only in the current thread.
038 * <p>
039 * An event marked {@link Event#isInline()} is dispatched immediately, otherwise it is recorded in a thread-based bundle
040 * of current events. If no transaction was started, an event marked {@link Event#isCommitEvent()} is used to flush the
041 * event bundle to its listeners, otherwise the transaction commit does the flush.
042 * <p>
043 * Listeners are of two types: {@link EventListener} notified as the event is raised and {@link PostCommitEventListener}
044 * notified after the transaction was committed.
045 */
046public interface EventService extends EventProducer {
047
048    /**
049     * Adds a new event listener. Used by the framework.
050     * <p>
051     * The event listener is described by a {@link EventListenerDescriptor} that may specify a priority. Both types of
052     * listeners (immediate and post-commit) are registered.
053     *
054     * @param listener the listener to add
055     */
056    void addEventListener(EventListenerDescriptor listener);
057
058    /**
059     * Removes an event listener. Used by the framework.
060     *
061     * @param listener the listener to remove
062     */
063    void removeEventListener(EventListenerDescriptor listener);
064
065    /**
066     * Fires an event given its name and a context.
067     *
068     * @param name the event name
069     * @param context the event context
070     */
071    void fireEvent(String name, EventContext context);
072
073    /**
074     * Fires an event.
075     * <p>
076     * If a transaction was started, the event is registered if needed to be sent after the transaction commit.
077     *
078     * @param event the event to fire
079     */
080    @Override
081    void fireEvent(Event event);
082
083    /**
084     * Fires all recorded events in a transaction. Used by the framework.
085     * <p>
086     * The events are fired to {@link PostCommitEventListener} listeners. Events are fired in the form of an event
087     * bundle.
088     *
089     * @param event the event bundle
090     */
091    @Override
092    void fireEventBundle(EventBundle event);
093
094    /**
095     * Fires an event bundle in synchronous mode. Used by the framework.
096     * <p>
097     * This means that asynchronous listeners will be run synchronously.
098     */
099    void fireEventBundleSync(EventBundle event);
100
101    /**
102     * Gets the list of the registered event listeners.
103     * <p>
104     * Modification on this list will not modify the internal lists in this {@link EventService}.
105     *
106     * @return the event listeners
107     */
108    List<EventListener> getEventListeners();
109
110    /**
111     * Get the list of the registered post commit event listeners.
112     * <p>
113     * Modification on this list will not modify the internal lists in this {@link EventService}.
114     *
115     * @return the post commit event listeners
116     */
117    List<PostCommitEventListener> getPostCommitEventListeners();
118
119    /**
120     * Gets the event listener descriptor corresponding to the give name.
121     *
122     * @since 5.8
123     * @param name the event listener name
124     * @return the descriptor, or {@code null} if not found
125     */
126    EventListenerDescriptor getEventListener(String name);
127
128    /**
129     * Waits until all asynchronous tasks are finished.
130     */
131    void waitForAsyncCompletion();
132
133    /**
134     * Waits until all asynchronous tasks are finished, but waits no longer than the given number of milliseconds.
135     *
136     * @param timeout the maximum time to wait for, in milliseconds
137     */
138    void waitForAsyncCompletion(long timeout);
139
140    /**
141     * Creates the registered domain event producers.
142     *
143     * @since 11.4
144     */
145    List<DomainEventProducer> createDomainEventProducers();
146
147}