00001 /* 00002 * ObservableMap.hpp 00003 * 00004 * Copyright (c) 2000, 2010, 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 * <p> 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 * <p> 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 com.tangosol.net.NamedCache 00042 * @see com.tangosol.net.cache.LocalCache 00043 * @see com.tangosol.util.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 * <p> 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 * <p> 00061 * To unregister the MapListener, use the 00062 * #removeMapListener(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 map listener that receives events based on a filter 00087 * evaluation. 00088 * <p> 00089 * The listeners will receive MapEvent objects, but if fLite is passed 00090 * as true, they <i>might</i> not contain the OldValue and NewValue 00091 * properties. 00092 * <p> 00093 * To unregister the MapListener, use the 00094 * {#removeMapListener(MapListener, Filter)} method. 00095 * 00096 * @param hListener the {MapEvent} listener to add 00097 * @param vFilter an optional filter that will be passed MapEvent 00098 * objects to select from; a MapEvent will be 00099 * delivered to the listener only if the filter 00100 * evaluates to true for that MapEvent (see 00101 * {com.tangosol.util.filter.MapEventFilter}); NULL 00102 * is equivalent to a filter that alway returns true 00103 * @param fLite an optional parameter where true indicates that 00104 * the {MapEvent} objects do not have to include the 00105 * OldValue and NewValue property values in order to 00106 * allow optimizations; default value is false 00107 * 00108 */ 00109 virtual void addFilterListener(MapListener::Handle hListener, 00110 Filter::View vFilter = NULL, bool fLite = false) = 0; 00111 00112 /** 00113 * Remove a map listener that previously signed up for events based on 00114 * a filter evaluation. 00115 * 00116 * @param hListener the listener to remove 00117 * @param vFilter the optional filter that was passed 00118 * into the corresponding addMapListener() call; 00119 * defaults to NULL 00120 */ 00121 virtual void removeFilterListener(MapListener::Handle hListener, 00122 Filter::View vFilter = NULL) = 0; 00123 }; 00124 00125 COH_CLOSE_NAMESPACE2 00126 00127 #endif // COH_OBSERVABLE_MAP_HPP 00128