00001 /* 00002 * Copyright (c) 2000, 2025, Oracle and/or its affiliates. 00003 * 00004 * Licensed under the Universal Permissive License v 1.0 as shown at 00005 * https://oss.oracle.com/licenses/upl. 00006 */ 00007 #ifndef COH_CACHE_EVENT_HPP 00008 #define COH_CACHE_EVENT_HPP 00009 00010 #include "coherence/lang.ns" 00011 00012 #include "coherence/util/MapEvent.hpp" 00013 #include "coherence/util/MapListener.hpp" 00014 #include "coherence/util/ObservableMap.hpp" 00015 00016 COH_OPEN_NAMESPACE3(coherence,net,cache) 00017 00018 using coherence::util::MapEvent; 00019 using coherence::util::MapListener; 00020 using coherence::util::ObservableMap; 00021 00022 00023 /** 00024 * An extension of the MapEvent which allows to differentiate between client 00025 * driven (natural) events and cache internal (synthetic) events. 00026 * 00027 * Consider a client code calling a remove() method for a cache. Quite 00028 * naturally it causes a corresponding entry_deleted event. However, the same 00029 * event could be as well caused by the client code calling put() forcing an 00030 * entry eviction. Alternatively, the put() method called by client code 00031 * naturally causes either entry_inserted or entry_updated event. However, the 00032 * same event could be as well caused by a client call to a get() method that 00033 * in turn forces an entry insertion by a cache loader. 00034 * 00035 * Not all cache service types support the dispatching of synthetic events. 00036 * Synthetic events will only be dispatched by a partitioned cache service 00037 * and its derivatives, such as a federated cache service, or by near, view, 00038 * or remote caches that are backed by a cache service that supports the 00039 * dispatching of synthetic events. In all other cases, no event will be dispatched 00040 * for synthetic events such as expiry. 00041 * 00042 * @author js 2008.06.06 00043 */ 00044 class COH_EXPORT CacheEvent 00045 : public class_spec<CacheEvent, 00046 extends<MapEvent> > 00047 { 00048 friend class factory<CacheEvent>; 00049 00050 00051 // ----- TransformationState enum --------------------------------------- 00052 00053 public: 00054 /** 00055 * Transformation state constants. 00056 * TransformationState describes how a CacheEvent has been or should be 00057 * transformed. 00058 */ 00059 enum TransformationState 00060 { 00061 /** 00062 * Value used to indicate that an event is non-transformable and should 00063 * not be passed to any transformer-based listeners. 00064 */ 00065 non_transformable, 00066 00067 /** 00068 * Value used to indicate that an event is transformable and could be 00069 * passed to transformer-based listeners. 00070 */ 00071 transformable, 00072 00073 /** 00074 * Value used to indicate that an event has been transformed, and should 00075 * only be passed to transformer-based listeners. 00076 */ 00077 transformed 00078 }; 00079 00080 00081 // ----- constructors --------------------------------------------------- 00082 00083 protected: 00084 /** 00085 * Create a new CacheEvent. 00086 * 00087 * @param hMap the map on which the Event initially 00088 * @param nId occurred the events id (entry_inserted | 00089 * entry_updated | entry_deleted) 00090 * @param voKey the key into the map 00091 * @param voValueOld the old value (for update and delete events) 00092 * @param voValueNew the new value (for insert and update events) 00093 * @param fSynthetic true iff the event is caused by internal 00094 * cache processing such as eviction or loading 00095 */ 00096 CacheEvent(ObservableMap::Handle hMap, int32_t nId, 00097 Object::View voKey, Object::View voValueOld, 00098 Object::View voValueNew, bool fSynthetic); 00099 00100 /** 00101 * Create a new CacheEvent. 00102 * 00103 * @param hMap the map on which the Event initially 00104 * @param nId occurred the events id (entry_inserted | 00105 * entry_updated | entry_deleted) 00106 * @param voKey the key into the map 00107 * @param voValueOld the old value (for update and delete events) 00108 * @param voValueNew the new value (for insert and update events) 00109 * @param fSynthetic true iff the event is caused by internal 00110 * cache processing such as eviction or loading 00111 * @param fPriming a flag indicating whether or not the event 00112 * is a priming event 00113 */ 00114 CacheEvent(ObservableMap::Handle hMap, int32_t nId, 00115 Object::View voKey, Object::View voValueOld, 00116 Object::View voValueNew, bool fSynthetic, bool fPriming); 00117 00118 /** 00119 * Create a new CacheEvent. 00120 * 00121 * @param hMap the map on which the Event initially 00122 * @param nId occurred the events id (entry_inserted | 00123 * entry_updated | entry_deleted) 00124 * @param voKey the key into the map 00125 * @param voValueOld the old value (for update and delete events) 00126 * @param voValueNew the new value (for insert and update events) 00127 * @param fSynthetic true iff the event is caused by internal 00128 * cache processing such as eviction or loading 00129 * @param nTransformState the TransformationState describing how 00130 * this event has been or should be transformed 00131 * @since Coherence 3.7.1.9 00132 */ 00133 CacheEvent(ObservableMap::Handle hMap, int32_t nId, 00134 Object::View voKey, Object::View voValueOld, 00135 Object::View voValueNew, bool fSynthetic, 00136 TransformationState nTransformState); 00137 00138 /** 00139 * Create a new CacheEvent. 00140 * 00141 * @param hMap the map on which the Event initially 00142 * @param nId occurred the events id (entry_inserted | 00143 * entry_updated | entry_deleted) 00144 * @param voKey the key into the map 00145 * @param voValueOld the old value (for update and delete events) 00146 * @param voValueNew the new value (for insert and update events) 00147 * @param fSynthetic true iff the event is caused by internal 00148 * cache processing such as eviction or loading 00149 * @param nTransformState the TransformationState describing how 00150 * this event has been or should be transformed 00151 * @param fPriming a flag indicating whether or not the event 00152 * is a priming event 00153 * @since 12.2.1.3.2 00154 */ 00155 CacheEvent(ObservableMap::Handle hMap, int32_t nId, 00156 Object::View voKey, Object::View voValueOld, 00157 Object::View voValueNew, bool fSynthetic, 00158 TransformationState nTransformState, bool fPriming); 00159 00160 /** 00161 * Constructs a new CacheEvent. 00162 * 00163 * @param map the ObservableMap object that fired the event 00164 * @param nId this event's id, one of (entry_inserted | 00165 * entry_updated | entry_deleted) 00166 * @param oKey the key into the map 00167 * @param oValueOld the old value (for update and delete events) 00168 * @param oValueNew the new value (for insert and update events) 00169 * @param fSynthetic true iff the event is caused by the cache 00170 * internal processing such as eviction or loading 00171 * @param transformState the TransformationState describing how 00172 * this event has been or should be transformed 00173 * @param fPriming a flag indicating whether or not the event 00174 * is a priming event 00175 * @param fExpired true iff the event results from an eviction 00176 * due to time 00177 * @since 22.06 00178 */ 00179 CacheEvent(ObservableMap::Handle hMap, int32_t nId, 00180 Object::View voKey, Object::View voValueOld, 00181 Object::View voValueNew, bool fSynthetic, 00182 TransformationState nTransformState, bool fPriming, 00183 bool fExpired); 00184 00185 private: 00186 /** 00187 * Blocked copy constructor. 00188 */ 00189 CacheEvent(const CacheEvent&); 00190 00191 // ----- CacheEvent interface ------------------------------------------- 00192 00193 public: 00194 /** 00195 * Return true iff this event is caused by internal cache processing 00196 * such as eviction or loading. 00197 * 00198 * @return true iff this event is caused by internal cache processing 00199 */ 00200 virtual bool isSynthetic() const; 00201 00202 /** 00203 * Return transformation state of this event. 00204 * Non-transformable events will not be delivered to MapEventTransformer 00205 * MapEventTransformer listeners. 00206 * 00207 * @return the TransformationState for this event 00208 */ 00209 virtual TransformationState getTransformState() const; 00210 00211 /** 00212 * Return true iff this event is caused by a priming listener registration. 00213 * 00214 * @return true iff this event is caused by a priming listener registration 00215 * @since 12.2.1.3.2 00216 */ 00217 virtual bool isPriming() const; 00218 00219 /** 00220 * Return true iff this event is caused by an entry eviction due to time limit reached. 00221 * In this case the event will also be synthetic. 00222 * 00223 * @return true iff this event results from a timed eviction 00224 * @since 22.06 00225 */ 00226 virtual bool isExpired() const; 00227 00228 protected: 00229 /** 00230 * {@inheritDoc} 00231 */ 00232 virtual bool shouldDispatch(TypedHandle<const MapListener> vListener) const; 00233 00234 00235 // ----- Describable interface ------------------------------------------ 00236 00237 public: 00238 /** 00239 * {@inheritDoc} 00240 */ 00241 virtual String::View getDescription() const; 00242 00243 00244 // ----- data members --------------------------------------------------- 00245 00246 protected: 00247 /** 00248 * Event cause flag. 00249 */ 00250 bool m_fSynthetic; 00251 00252 /** 00253 * The TransformationState for this event. 00254 */ 00255 TransformationState m_nTransformState; 00256 00257 /** 00258 * Flag indicating whether or not the event is a priming event (NearCache). 00259 * @since 12.2.1.3.2 00260 */ 00261 bool m_fPriming; 00262 00263 /** 00264 * Flag indicating whether the deletion event is a result of time expiration. 00265 * @since 22.06 00266 */ 00267 bool m_fExpired; 00268 }; 00269 00270 COH_CLOSE_NAMESPACE3 00271 00272 #endif // COH_CACHE_EVENT_HPP