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}