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}