Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/MapEvent.hpp

    00001 /*
    00002 * MapEvent.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_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

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