001/*
002 * Copyright (c) 2006-2012 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 *     bstefanescu
011 */
012package org.nuxeo.ecm.core.event;
013
014import java.io.Serializable;
015
016/**
017 * A lightweight object used by core components to notify interested components about events in core.
018 * <p>
019 * These events should be used by all core components not only by the repository.
020 * <p>
021 * The events may specify a set of control flags that can be used to control the visibility and the way post commit
022 * events are handled. There are 3 types of visibility:
023 * <ul>
024 * <li>LOCAL - events that are considered being visible to the local machine.
025 * <li>PUBLIC (the default) - events visible on any machine. Clearing this flag will avoid forwarding the event on
026 * remote machines (through JMS or other messaging systems)
027 * </ul>
028 * There are 2 post commit control flags:
029 * <ul>
030 * <li>INLINE - if true the event will not be recorded as part of the post commit event bundle. Defaults to false.
031 * <li>COMMIT - the event will simulate a commit so that the post commit event bundle will be fired. TYhe COMMIT flag is
032 * ignored while in a transaction.
033 * </ul>
034 * More flags may be added in the future.
035 *
036 * @author <a href="mailto:bs@nuxeo.com">Bogdan Stefanescu</a>
037 */
038public interface Event extends Serializable {
039
040    // we don't use an EnumSet, as they use far too much memory
041    int FLAG_NONE = 0;
042
043    int FLAG_CANCEL = 1;
044
045    int FLAG_ROLLBACK = 2;
046
047    int FLAG_COMMIT = 4;
048
049    int FLAG_LOCAL = 8;
050
051    int FLAG_INLINE = 16;
052
053    int FLAG_IMMEDIATE = 32;
054
055    int FLAG_BUBBLE_EXCEPTION = 64;
056
057    /**
058     * Gets the event name.
059     * <p>
060     * The name must be unique. It is recommended to use prefixes in the style of java package names to differentiate
061     * between similar events that are sent by different components.
062     */
063    String getName();
064
065    /**
066     * The time stamp when the event was raised.
067     *
068     * @return the time stamp as returned by {@link System#currentTimeMillis()}
069     */
070    long getTime();
071
072    /**
073     * Gets the event context.
074     * <p>
075     * Event contexts give access to the context in which the the event was raised. Event contexts are usually
076     * identifying the operation that raised the event. The context is exposing data objects linked to the event like
077     * documents and also may give access to the operation that raised the event allowing thus to canceling the
078     * operation, to record time spent to set the result status etc.
079     *
080     * @return the event context
081     */
082    EventContext getContext();
083
084    /**
085     * Gets the set of event flags
086     *
087     * @return the event flags
088     */
089    int getFlags();
090
091    /**
092     * Cancels this event.
093     * <p>
094     * This can be used by event listeners to exit the event notification. Remaining event listeners will no more be
095     * notified. Note that this is not canceling the underlying operation if any.
096     */
097    void cancel();
098
099    /**
100     * Checks whether the event was canceled.
101     *
102     * @return true if canceled, false otherwise.
103     */
104    boolean isCanceled();
105
106    /**
107     * Marks the event to bubble the Exception thrown by a listener.
108     * <p>
109     * This will exit the event listeners loop. The transaction won't be rollbacked, but the Exception will be thrown by
110     * the {@link EventService}.
111     *
112     * @since 5.7
113     */
114    void markBubbleException();
115
116    /**
117     * Returns {@code true} if the event was marked to bubble the Exception, {@code false} otherwise.
118     *
119     * @since 5.7
120     */
121    boolean isBubbleException();
122
123    /**
124     * Marks transaction for RollBack
125     * <p>
126     * This will exit the event listeners loop and throw a RuntimeException In JTA container, this will make the global
127     * transaction rollback.
128     */
129    void markRollBack();
130
131    /**
132     * Marks transaction for RollBack
133     * <p>
134     * This will exit the event listeners loop and throw a RuntimeException In JTA container, this will make the global
135     * transaction rollback.
136     *
137     * @param message message that explains the reason of the Rollback
138     * @param exception associated Exception that explains the Rollback if any
139     * @since 5.6
140     */
141    void markRollBack(String message, Exception exception);
142
143    /**
144     * Checks whether the event was marked for RollBack
145     *
146     * @return true if rolled back, false otherwise.
147     */
148    boolean isMarkedForRollBack();
149
150    /**
151     * Returns the Exception associated the RollBack if any
152     *
153     * @return the Exception associated the RollBack if any
154     * @since 5.6
155     */
156    Exception getRollbackException();
157
158    /**
159     * Returns the message associated to the RollBack if any
160     *
161     * @return the message associated to the RollBack if any
162     * @since 5.6
163     */
164    String getRollbackMessage();
165
166    /**
167     * Whether this event must not be added to a bundle. An event is not inline by default.
168     *
169     * @return true if the event must be omitted from event bundles, false otherwise.
170     */
171    boolean isInline();
172
173    /**
174     * Set the inline flag.
175     *
176     * @param isInline true if the event must not be recorded as part of the transaction
177     * @see #isInline()
178     */
179    void setInline(boolean isInline);
180
181    /**
182     * Tests whether or not this is a commit event. A commit event is triggering the post commit notification and then
183     * is reseting the recorded events.
184     *
185     * @return true if a commit event false otherwise
186     */
187    boolean isCommitEvent();
188
189    /**
190     * Set the commit flag.
191     *
192     * @param isCommit
193     * @see #isCommitEvent()
194     */
195    void setIsCommitEvent(boolean isCommit);
196
197    /**
198     * Tests if this event is local.
199     * <p>
200     * Local events events are of interest only on the local machine.
201     *
202     * @return true if private false otherwise
203     */
204    boolean isLocal();
205
206    /**
207     * Sets the local flag.
208     *
209     * @param isLocal
210     * @see #isLocal()
211     */
212    void setLocal(boolean isLocal);
213
214    /**
215     * Tests if this event is public.
216     * <p>
217     * Public events are of interest to everyone.
218     *
219     * @return true if public, false otherwise
220     */
221    boolean isPublic();
222
223    /**
224     * Set the public flag.
225     *
226     * @param isPublic
227     * @see #isPublic()
228     */
229    void setPublic(boolean isPublic);
230
231    /**
232     * Tests if event is Immediate
233     * <p>
234     * Immediate events are sent in bundle without waiting for a commit
235     *
236     * @return true if event is immediate, false otherwise
237     */
238    boolean isImmediate();
239
240    /**
241     * Sets the immediate flag.
242     */
243    void setImmediate(boolean immediate);
244
245}