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