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}