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 * 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:[email protected]">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_INLINE = 16;
050
051    int FLAG_IMMEDIATE = 32;
052
053    int FLAG_BUBBLE_EXCEPTION = 64;
054
055    /**
056     * Gets the event name.
057     * <p>
058     * The name must be unique. It is recommended to use prefixes in the style of java package names to differentiate
059     * between similar events that are sent by different components.
060     */
061    String getName();
062
063    /**
064     * The time stamp when the event was raised.
065     *
066     * @return the time stamp as returned by {@link System#currentTimeMillis()}
067     */
068    long getTime();
069
070    /**
071     * Gets the event context.
072     * <p>
073     * Event contexts give access to the context in which the the event was raised. Event contexts are usually
074     * identifying the operation that raised the event. The context is exposing data objects linked to the event like
075     * documents and also may give access to the operation that raised the event allowing thus to canceling the
076     * operation, to record time spent to set the result status etc.
077     *
078     * @return the event context
079     */
080    EventContext getContext();
081
082    /**
083     * Gets the set of event flags
084     *
085     * @return the event flags
086     */
087    int getFlags();
088
089    /**
090     * Cancels this event.
091     * <p>
092     * This can be used by event listeners to exit the event notification. Remaining event listeners will no more be
093     * notified. Note that this is not canceling the underlying operation if any.
094     */
095    void cancel();
096
097    /**
098     * Checks whether the event was canceled.
099     *
100     * @return true if canceled, false otherwise.
101     */
102    boolean isCanceled();
103
104    /**
105     * Marks the event to bubble the Exception thrown by a listener.
106     * <p>
107     * This will exit the event listeners loop. The transaction won't be rollbacked, but the Exception will be thrown by
108     * the {@link EventService}.
109     *
110     * @since 5.7
111     */
112    void markBubbleException();
113
114    /**
115     * Returns {@code true} if the event was marked to bubble the Exception, {@code false} otherwise.
116     *
117     * @since 5.7
118     */
119    boolean isBubbleException();
120
121    /**
122     * Marks transaction for RollBack
123     * <p>
124     * This will exit the event listeners loop and throw a RuntimeException In JTA container, this will make the global
125     * transaction rollback.
126     */
127    void markRollBack();
128
129    /**
130     * Marks transaction for RollBack
131     * <p>
132     * This will exit the event listeners loop and throw a RuntimeException In JTA container, this will make the global
133     * transaction rollback.
134     *
135     * @param message message that explains the reason of the Rollback
136     * @param exception associated Exception that explains the Rollback if any
137     * @since 5.6
138     */
139    void markRollBack(String message, Exception exception);
140
141    /**
142     * Checks whether the event was marked for RollBack
143     *
144     * @return true if rolled back, false otherwise.
145     */
146    boolean isMarkedForRollBack();
147
148    /**
149     * Returns the Exception associated the RollBack if any
150     *
151     * @return the Exception associated the RollBack if any
152     * @since 5.6
153     */
154    Exception getRollbackException();
155
156    /**
157     * Returns the message associated to the RollBack if any
158     *
159     * @return the message associated to the RollBack if any
160     * @since 5.6
161     */
162    String getRollbackMessage();
163
164    /**
165     * Whether this event must not be added to a bundle. An event is not inline by default.
166     *
167     * @return true if the event must be omitted from event bundles, false otherwise.
168     */
169    boolean isInline();
170
171    /**
172     * Set the inline flag.
173     *
174     * @param isInline true if the event must not be recorded as part of the transaction
175     * @see #isInline()
176     */
177    void setInline(boolean isInline);
178
179    /**
180     * Tests whether or not this is a commit event. A commit event is triggering the post commit notification and then
181     * is reseting the recorded events.
182     *
183     * @return true if a commit event false otherwise
184     */
185    boolean isCommitEvent();
186
187    /**
188     * Set the commit flag.
189     *
190     * @param isCommit
191     * @see #isCommitEvent()
192     */
193    void setIsCommitEvent(boolean isCommit);
194
195    /**
196     * @deprecated since 10.3
197     */
198    @Deprecated
199    default boolean isLocal() {
200        return false;
201    }
202
203    /**
204     * @deprecated since 10.3
205     */
206    @Deprecated
207    default void setLocal(boolean isLocal) {
208        // deprecated
209    }
210
211    /**
212     * @deprecated since 10.3
213     */
214    @Deprecated
215    default boolean isPublic() {
216        return true;
217    }
218
219    /**
220     * @deprecated since 10.3
221     */
222    @Deprecated
223    default void setPublic(boolean isPublic) {
224        // deprecated
225    }
226
227    /**
228     * Tests if event is Immediate
229     * <p>
230     * Immediate events are sent in bundle without waiting for a commit
231     *
232     * @return true if event is immediate, false otherwise
233     */
234    boolean isImmediate();
235
236    /**
237     * Sets the immediate flag.
238     */
239    void setImmediate(boolean immediate);
240
241}