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