00001 /* 00002 * ObservableMap.hpp 00003 * 00004 * Copyright (c) 2000, 2015, 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_OBSERVABLE_MAP_HPP 00017 #define COH_OBSERVABLE_MAP_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Filter.hpp" 00022 #include "coherence/util/Map.hpp" 00023 #include "coherence/util/MapListener.hpp" 00024 00025 COH_OPEN_NAMESPACE2(coherence,util) 00026 00027 00028 /** 00029 * ObservableMap interface represents an object with a model being 00030 * a Map that allows for pluggable notifications for occuring changes. 00031 * 00032 * This is primarily intended for maps that have automatic pruning and 00033 * purging strategies or maps that are asynchronously modified by different 00034 * threads. 00035 * 00036 * Starting from Coherence 2.3 it supports optimizations that optionally 00037 * do not require the map values to be included in the map events, 00038 * allowing a "lite" event to be delivered and saving memory, processing 00039 * and bandwidth for distributed applications. 00040 * 00041 * @see NamedCache 00042 * @see LocalCache 00043 * @see ObservableHashMap 00044 * 00045 * @author js 2008.06.04 00046 */ 00047 class COH_EXPORT ObservableMap 00048 : public interface_spec<ObservableMap, 00049 implements<Map> > 00050 { 00051 // ----- ObservableMap interface ---------------------------------------- 00052 00053 public: 00054 /** 00055 * Add a map listener for a specific key. 00056 * 00057 * The listeners will receive MapEvent objects, but if fLite is passed 00058 * as true, they <i>might</i> not contain the OldValue and NewValue 00059 * properties. 00060 * 00061 * To unregister the MapListener, use the 00062 * removeKeyListener(MapListener, Object) method. 00063 * 00064 * @param hListener the MapEvent listener to add 00065 * @param vKey the key that identifies the entry for which to 00066 * raise events 00067 * @param fLite true to indicate that the MapEvent objects do not 00068 * have to include the OldValue and NewValue 00069 * property values in order to allow optimizations 00070 */ 00071 virtual void addKeyListener(MapListener::Handle hListener, 00072 Object::View vKey, bool fLite) = 0; 00073 00074 /** 00075 * Remove a map listener that previously signed up for events about a 00076 * specific key. 00077 * 00078 * @param hListener the listener to remove 00079 * @param vKey the key that identifies the entry for which to 00080 * raise events 00081 */ 00082 virtual void removeKeyListener(MapListener::Handle hListener, 00083 Object::View vKey) = 0; 00084 00085 /** 00086 * Add a standard map listener that will receive all events (inserts, 00087 * updates, deletes) that occur against the map, with the key, old-value 00088 * and new-value included. This has the same result as the following call: 00089 * @code 00090 * addFilterListener(hListener, (Filter::View) NULL, false); 00091 * @endcode 00092 * 00093 * @param hListener the MapEvent listener to add 00094 * 00095 * @since Coherence 12.1.3 00096 */ 00097 virtual void addMapListener(MapListener::Handle hListener) = 0; 00098 00099 /** 00100 * Remove a standard map listener that previously signed up for all 00101 * events. This has the same result as the following call: 00102 * @code 00103 * removeFilterListener(hListener, (Filter::View) NULL); 00104 * @endcode 00105 * 00106 * @param hListener the listener to remove 00107 * 00108 * @since Coherence 12.1.3 00109 */ 00110 virtual void removeMapListener(MapListener::Handle hListener) = 0; 00111 00112 /** 00113 * Add a map listener that receives events based on a filter 00114 * evaluation. 00115 * 00116 * The listeners will receive MapEvent objects, but if fLite is passed 00117 * as true, they <i>might</i> not contain the OldValue and NewValue 00118 * properties. 00119 * 00120 * To unregister the MapListener, use the 00121 * removeFilterListener(MapListener, Filter) method. 00122 * 00123 * @param hListener the MapEvent listener to add 00124 * @param vFilter an optional filter that will be passed MapEvent 00125 * objects to select from; a MapEvent will be 00126 * delivered to the listener only if the filter 00127 * evaluates to true for that MapEvent (see 00128 * {com.tangosol.util.filter.MapEventFilter}); NULL 00129 * is equivalent to a filter that alway returns true 00130 * @param fLite an optional parameter where true indicates that 00131 * the {MapEvent} objects do not have to include the 00132 * OldValue and NewValue property values in order to 00133 * allow optimizations; default value is false 00134 * 00135 */ 00136 virtual void addFilterListener(MapListener::Handle hListener, 00137 Filter::View vFilter = NULL, bool fLite = false) = 0; 00138 00139 /** 00140 * Remove a map listener that previously signed up for events based on 00141 * a filter evaluation. 00142 * 00143 * @param hListener the listener to remove 00144 * @param vFilter the optional filter that was passed 00145 * into the corresponding addFilterListener() call; 00146 * defaults to NULL 00147 */ 00148 virtual void removeFilterListener(MapListener::Handle hListener, 00149 Filter::View vFilter = NULL) = 0; 00150 }; 00151 00152 COH_CLOSE_NAMESPACE2 00153 00154 #endif // COH_OBSERVABLE_MAP_HPP 00155