Oracle Coherence for C++ API
Release 3.6.1.0
E18813-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/MapListenerSupport.hpp

    00001 /*
    00002 * MapListenerSupport.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_MAP_LISTENER_SUPPORT_HPP
    00017 #define COH_MAP_LISTENER_SUPPORT_HPP
    00018
    00019 #include "coherence/lang.ns"
    00020
    00021 #include "coherence/net/cache/CacheEvent.hpp"
    00022 #include "coherence/util/Converter.hpp"
    00023 #include "coherence/util/Filter.hpp"
    00024 #include "coherence/util/Listeners.hpp"
    00025 #include "coherence/util/MapEvent.hpp"
    00026 #include "coherence/util/MapListener.hpp"
    00027 #include "coherence/util/Set.hpp"
    00028
    00029 COH_OPEN_NAMESPACE2(coherence,util)
    00030
    00031 using coherence::net::cache::CacheEvent;
    00032
    00033
    00034 /**
    00035 * This class provides support for advanced MapListener functionality.
    00036 *
    00037 * @author js  2008.06.10
    00038 */
    00039 class COH_EXPORT MapListenerSupport
    00040     : public class_spec<MapListenerSupport>
    00041     {
    00042     friend class factory<MapListenerSupport>;
    00043
    00044     // ----- constructors ---------------------------------------------------
    00045
    00046     protected:
    00047         /**
    00048         * Create a new MapListenerSupport.
    00049         */
    00050         MapListenerSupport();
    00051
    00052
    00053     // ----- MapListenerSupport interface -----------------------------------
    00054
    00055     public:
    00056         /**
    00057         * Add a map listener that receives events based on a filter
    00058         * evaluation.
    00059         *
    00060         * @param hListener  the listener to add
    00061         * @param vFilter    a filter that will be passed MapEvent objects to
    00062         *                   select from; a MapEvent will be delivered to the
    00063         *                   listener only if the filter evaluates to true for
    00064         *                   that MapEvent; NULL is equivalent to a filter
    00065         *                   that alway returns true
    00066         * @param fLite      true to indicate that the MapEvent objects do not
    00067         *                   have to include the OldValue and NewValue
    00068         *                   property values in order to allow optimizations
    00069         */
    00070         virtual void addListener(MapListener::Handle hListener,
    00071                 Filter::View vFilter, bool fLite);
    00072
    00073         /**
    00074         * Add a map listener for a specific key.
    00075         *
    00076         * @param hListener  the listener to add
    00077         * @param vKey       the key that identifies the entry for which to
    00078         *                   raise events
    00079         * @param fLite      true to indicate that the MapEvent objects do not
    00080         *                   have to include the OldValue and NewValue
    00081         *                   property values in order to allow optimizations
    00082         *
    00083         */
    00084         virtual void addListener(MapListener::Handle hListener,
    00085                 Object::View vKey, bool fLite);
    00086
    00087         /**
    00088         * Remove a map listener that previously signed up for events based on
    00089         * a filter evaluation.
    00090         *
    00091         * @param vListener  the listener to remove
    00092         * @param vFilter    a filter used to evaluate events
    00093         */
    00094         virtual void removeListener(MapListener::View vListener,
    00095                 Filter::View vFilter);
    00096
    00097         /**
    00098         * Remove a map listener that previously signed up for events about a
    00099         * specific key.
    00100         *
    00101         * @param vListener  the listener to remove
    00102         * @param vKey       the key that identifies the entry for which to
    00103         *                   raise events
    00104         */
    00105         virtual void removeListener(MapListener::View vListener,
    00106                 Object::View vKey);
    00107
    00108         /**
    00109         * Remove all signed up listeners.
    00110         */
    00111         virtual void clear();
    00112
    00113         /**
    00114         * Checks whether or not this MapListenerSupport object contains
    00115         * any listeners.
    00116         *
    00117         * @return true iff there are no listeners encapsulated by this
    00118         *         MapListenerSupport object
    00119         */
    00120         virtual bool isEmpty() const;
    00121
    00122         /**
    00123         * Checks whether or not this MapListenerSupport object contains
    00124         * any listeners for a given filter.
    00125         *
    00126         * @param vFilter  the filter
    00127         *
    00128         * @return true iff there are no listeners for the specified filter
    00129         *              encapsulated by this MapListenerSupport object
    00130         */
    00131         virtual bool isEmpty(Filter::View vFilter) const;
    00132
    00133         /**
    00134         * Checks whether or not this MapListenerSupport object contains
    00135         * any listeners for a given key.
    00136         *
    00137         * @param vKey  the key
    00138         *
    00139         * @return true iff there are no listeners for the specified filter
    00140         *              encapsulated by this MapListenerSupport object
    00141         */
    00142         virtual bool isEmpty(Object::View vKey) const;
    00143
    00144         /**
    00145         * Checks whether or not this MapListenerSupport object contains
    00146         * any standard (not lite) listeners for a given filter.
    00147         *
    00148         * @param vFilter  the filter
    00149         *
    00150         * @return true iff there are no standard listeners for the specified
    00151         *              filter encapsulated by this MapListenerSupport object
    00152         */
    00153         virtual bool containsStandardListeners(
    00154                 Filter::View vFilter) const;
    00155
    00156         /**
    00157         * Checks whether or not this MapListenerSupport object contains
    00158         * any standard (not lite) listeners for a given key.
    00159         *
    00160         * @param vKey  the key
    00161         *
    00162         * @return true iff there are no standard listeners for the specified
    00163         *              filter encapsulated by this MapListenerSupport object
    00164         */
    00165         virtual bool containsStandardListeners(Object::View vKey) const;
    00166
    00167         /**
    00168         * Obtain a set of all filters that have assosiated global listeners.
    00169         * <p>
    00170         * <b>Note</b>: The returned value must be treated as an immutable.
    00171         *
    00172         * @return a set of all filters that have assosiated global listeners
    00173         */
    00174         virtual Set::View getFilterSet() const;
    00175
    00176         /**
    00177         * Obtain a set of all keys that have assosiated key listeners.
    00178         * <p>
    00179         * <b>Note</b>: The returned value must be treated as an immutable.
    00180         *
    00181         * @return a set of all keys that have assosiated key listeners
    00182         */
    00183         virtual Set::View getKeySet() const;
    00184
    00185         /**
    00186         * Obtain the Listeners object for a given filter.
    00187         *
    00188         * @param vFilter  the filter
    00189         *
    00190         * @return the Listeners object for the filter; NULL if none exists
    00191         */
    00192         virtual Listeners::View getListeners(Filter::View vFilter) const;
    00193
    00194         /**
    00195         * Obtain the Listeners object for a given key.
    00196         *
    00197         * @param vKey  the key
    00198         *
    00199         * @return the Listeners object for the key; NULL if none exists
    00200         */
    00201         virtual Listeners::View getListeners(Object::View vKey) const;
    00202
    00203         /**
    00204         * Collect all Listeners that should be notified for a given event.
    00205         * <p>
    00206         * <b>Note</b>: The returned value must be treated as an immutable.
    00207         *
    00208         * @param vEvent the MapEvent object
    00209         *
    00210         * @return the Listeners object containing the relevant listeners
    00211         */
    00212         virtual Listeners::View collectListeners(MapEvent::View vEvent);
    00213
    00214         /**
    00215         * Fire the specified map event.
    00216         *
    00217         * @param hEvent    the map event
    00218         * @param fStrict   if true then any RuntimeException thrown by event
    00219         *                  handlers stops all further event processing and
    00220         *                  the exception is re-thrown; if false then all
    00221         *                  exceptions are logged and the process continues
    00222         */
    00223         virtual void fireEvent(MapEvent::Handle hEvent, bool fStrict);
    00224
    00225         /**
    00226         * Convert the specified map event into another MapEvent that ensures
    00227         * the lazy event data conversion using the specified converters.
    00228         *
    00229         * @param vEvent    the map event
    00230         * @param hmapConv  the source for the converted event
    00231         * @param vConvKey  (optional) the key Converter
    00232         * @param vConvVal  (optional) the value converter
    00233         *
    00234         * @return the converted MapEvent object
    00235         */
    00236         static MapEvent::Handle convertEvent(MapEvent::View vEvent,
    00237                 ObservableMap::Handle hmapConv,
    00238                 Converter::View vConvKey = NULL,
    00239                 Converter::View vConvVal = NULL);
    00240
    00241
    00242     // ----- helper methods -------------------------------------------------
    00243
    00244     protected:
    00245         /**
    00246         * Ensure that the specified map has a Listeners object assosiated
    00247         * with the specified key and add the specified listener to it.
    00248         *
    00249         * @param hmapListeners  map of listeners
    00250         * @param vKey           key of the listener
    00251         * @param hListener      the listener to add
    00252         */
    00253         static void addSafeListener(Map::Handle hmapListeners,
    00254                 Object::View vKey, MapListener::Handle hListener);
    00255
    00256         /**
    00257         * Remove the specified listener from the Listeners object assosiated
    00258         * with the specified key.
    00259         *
    00260         * @param hmapListeners  map of listeners
    00261         * @param vKey           key of the listener
    00262         * @param vListener      the listener to remove
    00263         */
    00264         static void removeSafeListener(Map::Handle hmapListeners,
    00265                 Object::View vKey, MapListener::View vListener);
    00266
    00267         /**
    00268         * Add a state information (lite or standard) associated with
    00269         * specified key and listener.
    00270         *
    00271         * @param hmapStandardListeners  map of standard listeners
    00272         * @param vKey                   key of the listener
    00273         * @param hListener              the listener to add
    00274         * @param fLite                  true to indicate that the MapEvent
    00275         *                               objects do not have to include the
    00276         *                               OldValue and NewValue property values
    00277         */
    00278         static void addListenerState(Map::Handle hmapStandardListeners,
    00279                 Object::View vKey, MapListener::Handle hListener,
    00280                 bool fLite);
    00281
    00282         /**
    00283         * Remove a state information (lite or standard) assosiated with
    00284         * specified key and listener.
    00285         *
    00286         * @param hmapStandardListeners  map of standard listeners
    00287         * @param vKey                   key of the listener
    00288         * @param vListener              the listener to remove
    00289         */
    00290         static void removeListenerState(Map::Handle hmapStandardListeners,
    00291                 Object::View vKey, MapListener::View vListener);
    00292
    00293
    00294     // ----- Object interface -----------------------------------------------
    00295
    00296     public:
    00297         /**
    00298         * {@inheritDoc}
    00299         */
    00300         virtual void toStream(std::ostream& out) const;
    00301
    00302
    00303     // ----- inner class: FilterEvent ---------------------------------------
    00304
    00305     public:
    00306         /**
    00307         * An extension of the CacheEvent which may carry no values (old or
    00308         * new), but instead holds an array of Filter objects being the
    00309         * "cause" of the event.
    00310         */
    00311         class COH_EXPORT FilterEvent
    00312             : public class_spec<FilterEvent,
    00313                 extends<CacheEvent> >
    00314             {
    00315             friend class factory<FilterEvent>;
    00316
    00317             // ----- constructors ---------------------------------------
    00318
    00319             protected:
    00320                 /**
    00321                 * Create a new FilterEvent with no old and new values.
    00322                 *
    00323                 * @param hMap        the map on which the Event initially
    00324                 *                    occurred
    00325                 * @param nId         the events id (ENTRY_INSERTED |
    00326                 *                    ENTRY_UPDATED | ENTRY_DELETED)
    00327                 * @param vKey        the key into the map
    00328                 * @param fSynthetic  true iff the event is caused by internal
    00329                 *                    cache processing such as eviction or
    00330                 *                    loading
    00331                 * @param haFilters   an array of Filters
    00332                 */
    00333                 FilterEvent(ObservableMap::Handle hMap, int32_t nId,
    00334                         Object::View vKey, Object::View vValueOld,
    00335                         Object::View vValueNew, bool fSynthetic,
    00336                         ObjectArray::Handle haFilters);
    00337
    00338             // ----- FilterEvent interface ------------------------------
    00339
    00340             public:
    00341                 /**
    00342                 * Return an array of filters that are the cause of this
    00343                 * event.
    00344                 *
    00345                 * @return an array of filters
    00346                 */
    00347                 virtual ObjectArray::View getFilter() const;
    00348
    00349
    00350             // ----- Describable interface ------------------------------
    00351
    00352             public:
    00353                 /**
    00354                 * {@inheritDoc}
    00355                 */
    00356                 virtual void outputDescription(std::ostream& out) const;
    00357
    00358             // ----- helper methods -------------------------------------
    00359
    00360             public:
    00361                 /**
    00362                 * Determine if this filter event contains a specified filter.
    00363                 *
    00364                 * @param vFilter  the filter to search for
    00365                 *
    00366                 * @return true if the event contained the specified filter,
    00367                 *         false otherwise
    00368                 */
    00369                 virtual bool containsFilter(Filter::View vFilter) const;
    00370
    00371             // ----- data members ---------------------------------------
    00372
    00373             protected:
    00374                 /**
    00375                 * Filters which caused the event.
    00376                 */
    00377                 MemberHandle<ObjectArray> m_haFilters;
    00378             };
    00379
    00380
    00381     // ----- inner class: SynchronousListener -------------------------------
    00382
    00383     public:
    00384         /**
    00385         * A tag interface indicating that tagged MapListener implementation
    00386         * has to receive the MapEvent notifications in a synchronous manner.
    00387         * <p>
    00388         * Consider a MapListener that subscribes to receive notifications for
    00389         * distributed (partitioned) cache. All events notifications are
    00390         * received by the service thread and immediately queued to be
    00391         * processed by the dedicated event dispatcher thread. This makes it
    00392         * impossible to differentiate between the event caused by the updates
    00393         * made by this thread and any other thread (possibly in a different
    00394         * VM). Forcing the events to be processed on the service thread
    00395         * guarantees that by the time "put" or "remove" requests return to
    00396         * the caller all relevant MapEvent notification have been processed
    00397         * (due to the "in order delivery" rule enforced by the TCMP).
    00398         * <p>
    00399         * This interface should be considered as a very advanced feature, so
    00400         * a MapListener implementation that is tagged as a
    00401         * SynchronousListener must exercise extreme caution during event
    00402         * processing since any delay with return or unhandled exception will
    00403         * cause a delay or complete shutdown of the corresponding cache
    00404         * service.
    00405         * <p>
    00406         * <b>Note:</b> The contract by the event producer in respect to the
    00407         * SynchronousListener is somewhat weaker then the general one.
    00408         * First, the SynchronousListener implementaion should make no
    00409         * assumptions about the event source obtained by {MapEvent#getMap()}.
    00410         * Second, in the event of [automatic] service restart, the listener
    00411         * has to be re-registered manually (for example, in response to the
    00412         * {com::tangosol::net::MemberEvent#MEMBER_JOINED MEMBER_JOINED}
    00413         * event). Third, and the most important, no calls against the
    00414         * NamedCache are allowed during the synchronous event processing (the
    00415         * only exception being a call to remove the listener itself).
    00416         */
    00417         class COH_EXPORT SynchronousListener
    00418             : public interface_spec<SynchronousListener,
    00419                 implements<MapListener> >
    00420             {
    00421             };
    00422
    00423
    00424     // ----- inner class: WrapperSynchronousListener ------------------------
    00425
    00426     public:
    00427         /**
    00428         * A wrapper class that turns the specified MapListener into
    00429         * a synchronous listener.
    00430         */
    00431         class COH_EXPORT WrapperSynchronousListener
    00432             : public class_spec<WrapperSynchronousListener,
    00433                 extends<Object>,
    00434                 implements<SynchronousListener> >
    00435             {
    00436             friend class factory<WrapperSynchronousListener>;
    00437
    00438             // ----- constructors ---------------------------------------
    00439
    00440             protected:
    00441                 /**
    00442                 * Create a new WrapperSynchronousListener.
    00443                 *
    00444                 * @param hListener  the listener to be wrapped
    00445                 *
    00446                 * @return the new WrapperSynchronousListener instance
    00447                 */
    00448                 WrapperSynchronousListener(MapListener::Handle hListener);
    00449
    00450             // ----- MapListener interface ------------------------------
    00451
    00452             public:
    00453                 /**
    00454                 * {@inheritDoc}
    00455                 */
    00456                 virtual void entryInserted(MapEvent::View vEvent);
    00457
    00458                 /**
    00459                 * {@inheritDoc}
    00460                 */
    00461                 virtual void entryUpdated(MapEvent::View vEvent);
    00462
    00463                 /**
    00464                 * {@inheritDoc}
    00465                 */
    00466                 virtual void entryDeleted(MapEvent::View vEvent);
    00467
    00468             // ----- Object interface -----------------------------------
    00469
    00470             public:
    00471                 /**
    00472                 * {@inheritDoc}
    00473                 */
    00474                 virtual size32_t hashCode() const;
    00475
    00476                 /**
    00477                 * {@inheritDoc}
    00478                 */
    00479                 virtual bool equals(Object::View v) const;
    00480
    00481             // ----- data members ---------------------------------------
    00482
    00483             protected:
    00484                 /**
    00485                 * Wrapped MapListener.
    00486                 */
    00487                 MemberHandle<MapListener> m_hListener;
    00488             };
    00489
    00490
    00491     // ----- enums ----------------------------------------------------------
    00492
    00493     protected:
    00494         /**
    00495         * Optimization Plan enum.
    00496         */
    00497         enum Plan
    00498             {
    00499             NONE,          // A plan has not yet been formed
    00500             NO_LISTENERS,  // There are no listeners
    00501             ALL_LISTENER,  // There is one all-keys non-filtered listener
    00502             KEY_LISTENER,  // One key listener (even if for multiple keys)
    00503             NO_OPTIMIZE    // No optimized plan, use the default approach
    00504             };
    00505
    00506
    00507     // ----- data members ---------------------------------------------------
    00508
    00509     protected:
    00510          /**
    00511         * The collections of MapListener objects that have signed up for
    00512         * notifications from an ObservableMap implementation keyed by the
    00513         * corresponding Filter objects.
    00514         */
    00515         MemberHandle<Map> m_hmapListeners;
    00516
    00517         /**
    00518         * The collections of MapListener objects that have signed up for key
    00519         * based notifications from an ObservableMap implementation keyed by
    00520         * the corresponding key objects.
    00521         */
    00522         MemberHandle<Map> m_hmapKeyListeners;
    00523
    00524         // consider adding listener tag support to Listeners class, which
    00525         // would allow getting rid of the following data structures ...
    00526         /**
    00527         * The subset of standard (not lite) global listeners. The keys are
    00528         * the Filter objects, the values are sets of corresponding standard
    00529         * listeners.
    00530         */
    00531         MemberHandle<Map> m_hmapStandardListeners;
    00532
    00533         /**
    00534         * The subset of standard (not lite) key listeners. The keys are the
    00535         * key objects, the values are sets of corresponding standard
    00536         * listeners.
    00537         */
    00538         MemberHandle<Map> m_hmapStandardKeyListeners;
    00539
    00540         /**
    00541         * The optimization plan which indicates the fastest way to put
    00542         * together a set of listeners.
    00543         */
    00544         Plan m_optimizationPlan;
    00545
    00546         /**
    00547         * A cached set of Listeners.
    00548         */
    00549         MemberView<Listeners> m_vListenersCached;
    00550     };
    00551
    00552 COH_CLOSE_NAMESPACE2
    00553
    00554 #endif // COH_MAP_LISTENER_SUPPORT_HPP
    00555

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.