00001 /* 00002 * MapEvent.hpp 00003 * 00004 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_MAP_EVENT_HPP 00017 #define COH_MAP_EVENT_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/EventObject.hpp" 00022 #include "coherence/util/Listeners.hpp" 00023 00024 COH_OPEN_NAMESPACE2(coherence,util) 00025 00026 class MapListener; 00027 class ObservableMap; 00028 00029 /** 00030 * An event which indicates that the content of a map has changed: 00031 * <ul> 00032 * <li>an entry has been added</li> 00033 * <li>an entry has been removed</li> 00034 * <li>an entry has been changed</li> 00035 * </ul> 00036 * A MapEvent object is sent as an argument to the MapListener interface 00037 * methods. NULL values may be provided for the old and the new values. 00038 * 00039 * @author js 2008.06.03 00040 */ 00041 class COH_EXPORT MapEvent 00042 : public class_spec<MapEvent, 00043 extends<EventObject> > 00044 { 00045 friend class factory<MapEvent>; 00046 00047 // ----- constructors --------------------------------------------------- 00048 00049 protected: 00050 /** 00051 * Create a MapEvent. 00052 * 00053 * @param hMap the map on which the Event initially occurred 00054 * @param nId the events id (entry_inserted | entry_updated | 00055 * entry_deleted) 00056 * @param vKey the key into the map 00057 * @param vValueOld the old value (for update and delete events) 00058 * @param vValueNew the new value (for insert and update events) 00059 */ 00060 MapEvent(TypedHandle<ObservableMap> hMap, int32_t nId, Object::View vKey, 00061 Object::View vValueOld, Object::View vValueNew); 00062 00063 private: 00064 /** 00065 * Blocked copy constructor. 00066 */ 00067 MapEvent(const MapEvent&); 00068 00069 00070 // ----- MapEvent interface --------------------------------------------- 00071 00072 public: 00073 /** 00074 * Return an ObservableMap object on which this event has actually 00075 * occured. 00076 * 00077 * @return an ObservableMap object 00078 */ 00079 virtual TypedHandle<ObservableMap> getMap() const; 00080 00081 /** 00082 * Return this event's id. The event id is one of the entry_* 00083 * enumerated constants. 00084 * 00085 * @return an id 00086 */ 00087 virtual int32_t getId() const; 00088 00089 /** 00090 * Return a key associated with this event. 00091 * 00092 * @return a key 00093 */ 00094 virtual Object::View getKey() const; 00095 00096 /** 00097 * Return an old value associated with this event. 00098 * <p> 00099 * The old value represents a value deleted from or updated in a map. 00100 * It is always NULL for "insert" notifications. 00101 * 00102 * @return an old value 00103 */ 00104 virtual Object::View getOldValue() const; 00105 00106 /** 00107 * Return a new value associated with this event. 00108 * <p> 00109 * The new value represents a new value inserted into or updated in 00110 * a map. It is always NULL for "delete" notifications. 00111 * 00112 * @return a new value 00113 */ 00114 virtual Object::View getNewValue() const; 00115 00116 00117 // ----- Object interface ----------------------------------------------- 00118 00119 public: 00120 /** 00121 * {@inheritDoc} 00122 */ 00123 virtual void toStream(std::ostream& out) const; 00124 00125 00126 // ----- helper methods ------------------------------------------------- 00127 00128 public: 00129 /** 00130 * Dispatch this event to the specified listeners collection. 00131 * <p> 00132 * This call is equivalent to 00133 * <pre> 00134 * dispatch(listeners, true); 00135 * </pre> 00136 * 00137 * @param vListeners the listeners collection 00138 * 00139 * @throws ClassCastException if any of the targets is not 00140 * an instance of MapListener interface 00141 */ 00142 virtual void dispatch(Listeners::View vListeners) const; 00143 00144 /** 00145 * Dispatch this event to the specified listeners collection. 00146 * 00147 * @param vListeners the listeners collection 00148 * @param fStrict if true then any RuntimeException thrown by event 00149 * handlers stops all further event processing and 00150 * the exception is re-thrown; if false then all 00151 * exceptions are logged and the process continues 00152 * 00153 * @throws ClassCastException if any of the targets is not 00154 * an instance of MapListener interface 00155 */ 00156 virtual void dispatch(Listeners::View vListeners, 00157 bool fStrict) const; 00158 00159 /** 00160 * Dispatch this event to the specified MapListener. 00161 * 00162 * @param hListener the listener 00163 */ 00164 virtual void dispatch(TypedHandle<MapListener> hListener) const; 00165 00166 /** 00167 * Convert an event ID into a human-readable string. 00168 * 00169 * @param nId an event ID, one of the entry_* enumerated values 00170 * 00171 * @return a corresponding human-readable string, for example 00172 * "inserted" 00173 */ 00174 static String::View getDescription(int32_t nId); 00175 00176 using Describable::getDescription; 00177 00178 // ----- Describable interface ------------------------------------------ 00179 00180 public: 00181 /** 00182 * {@inheritDoc} 00183 */ 00184 virtual void outputDescription(std::ostream& out) const; 00185 00186 00187 // ----- constants ------------------------------------------------------ 00188 00189 public: 00190 /** 00191 * This event indicates that an entry has been added to the map. 00192 */ 00193 static const int32_t entry_inserted = 1; 00194 00195 /** 00196 * This event indicates that an entry has been updated in the map. 00197 */ 00198 static const int32_t entry_updated = 2; 00199 00200 /** 00201 * This event indicates that an entry has been removed from the map. 00202 */ 00203 static const int32_t entry_deleted = 3; 00204 00205 00206 // ----- data members --------------------------------------------------- 00207 00208 protected: 00209 /** 00210 * The event's id. 00211 */ 00212 int32_t m_nId; 00213 00214 /** 00215 * A key. This is mutable because subclasses may lazily initialize 00216 * this value from an accessor. 00217 */ 00218 mutable MemberView<Object> m_voKey; 00219 00220 /** 00221 * A previous value. May be NULL if not known. This is mutable 00222 * because subclasses may lazily initialize this value from an 00223 * accessor. 00224 */ 00225 mutable MemberView<Object> m_voValueOld; 00226 00227 /** 00228 * A new value. May be NULL if not known. This is mutable because 00229 * subclasses may lazily initialize this value from an accessor. 00230 */ 00231 mutable MemberView<Object> m_voValueNew; 00232 }; 00233 00234 COH_CLOSE_NAMESPACE2 00235 00236 #endif // COH_MAP_EVENT_HPP 00237