00001 /* 00002 * MapEvent.hpp 00003 * 00004 * Copyright (c) 2000, 2011, 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 00064 // ----- MapEvent interface --------------------------------------------- 00065 00066 public: 00067 /** 00068 * Return an ObservableMap object on which this event has actually 00069 * occured. 00070 * 00071 * @return an ObservableMap object 00072 */ 00073 virtual TypedHandle<ObservableMap> getMap() const; 00074 00075 /** 00076 * Return this event's id. The event id is one of the entry_* 00077 * enumerated constants. 00078 * 00079 * @return an id 00080 */ 00081 virtual int32_t getId() const; 00082 00083 /** 00084 * Return a key associated with this event. 00085 * 00086 * @return a key 00087 */ 00088 virtual Object::View getKey() const; 00089 00090 /** 00091 * Return an old value associated with this event. 00092 * <p> 00093 * The old value represents a value deleted from or updated in a map. 00094 * It is always NULL for "insert" notifications. 00095 * 00096 * @return an old value 00097 */ 00098 virtual Object::View getOldValue() const; 00099 00100 /** 00101 * Return a new value associated with this event. 00102 * <p> 00103 * The new value represents a new value inserted into or updated in 00104 * a map. It is always NULL for "delete" notifications. 00105 * 00106 * @return a new value 00107 */ 00108 virtual Object::View getNewValue() const; 00109 00110 00111 // ----- Object interface ----------------------------------------------- 00112 00113 public: 00114 /** 00115 * {@inheritDoc} 00116 */ 00117 virtual void toStream(std::ostream& out) const; 00118 00119 00120 // ----- helper methods ------------------------------------------------- 00121 00122 public: 00123 /** 00124 * Dispatch this event to the specified listeners collection. 00125 * <p> 00126 * This call is equivalent to 00127 * <pre> 00128 * dispatch(listeners, true); 00129 * </pre> 00130 * 00131 * @param vListeners the listeners collection 00132 * 00133 * @throws ClassCastException if any of the targets is not 00134 * an instance of MapListener interface 00135 */ 00136 virtual void dispatch(Listeners::View vListeners) const; 00137 00138 /** 00139 * Dispatch this event to the specified listeners collection. 00140 * 00141 * @param vListeners the listeners collection 00142 * @param fStrict if true then any RuntimeException thrown by event 00143 * handlers stops all further event processing and 00144 * the exception is re-thrown; if false then all 00145 * exceptions are logged and the process continues 00146 * 00147 * @throws ClassCastException if any of the targets is not 00148 * an instance of MapListener interface 00149 */ 00150 virtual void dispatch(Listeners::View vListeners, 00151 bool fStrict) const; 00152 00153 /** 00154 * Dispatch this event to the specified MapListener. 00155 * 00156 * @param hListener the listener 00157 */ 00158 virtual void dispatch(TypedHandle<MapListener> hListener) const; 00159 00160 /** 00161 * Convert an event ID into a human-readable string. 00162 * 00163 * @param nId an event ID, one of the entry_* enumerated values 00164 * 00165 * @return a corresponding human-readable string, for example 00166 * "inserted" 00167 */ 00168 static String::View getDescription(int32_t nId); 00169 00170 using Describable::getDescription; 00171 00172 // ----- Describable interface ------------------------------------------ 00173 00174 public: 00175 /** 00176 * {@inheritDoc} 00177 */ 00178 virtual void outputDescription(std::ostream& out) const; 00179 00180 00181 // ----- constants ------------------------------------------------------ 00182 00183 public: 00184 /** 00185 * This event indicates that an entry has been added to the map. 00186 */ 00187 static const int32_t entry_inserted = 1; 00188 00189 /** 00190 * This event indicates that an entry has been updated in the map. 00191 */ 00192 static const int32_t entry_updated = 2; 00193 00194 /** 00195 * This event indicates that an entry has been removed from the map. 00196 */ 00197 static const int32_t entry_deleted = 3; 00198 00199 00200 // ----- data members --------------------------------------------------- 00201 00202 protected: 00203 /** 00204 * The event's id. 00205 */ 00206 int32_t m_nId; 00207 00208 /** 00209 * A key. This is mutable because subclasses may lazily initialize 00210 * this value from an accessor. 00211 */ 00212 mutable MemberView<Object> m_voKey; 00213 00214 /** 00215 * A previous value. May be NULL if not known. This is mutable 00216 * because subclasses may lazily initialize this value from an 00217 * accessor. 00218 */ 00219 mutable MemberView<Object> m_voValueOld; 00220 00221 /** 00222 * A new value. May be NULL if not known. This is mutable because 00223 * subclasses may lazily initialize this value from an accessor. 00224 */ 00225 mutable MemberView<Object> m_voValueNew; 00226 }; 00227 00228 COH_CLOSE_NAMESPACE2 00229 00230 #endif // COH_MAP_EVENT_HPP 00231