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}