Oracle Coherence for C++ API
Release 3.6.0.0

E15728-01

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.