coherence/util/MapEvent.hpp

/*
* MapEvent.hpp
*
* Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.
*
* Oracle is a registered trademarks of Oracle Corporation and/or its
* affiliates.
*
* This software is the confidential and proprietary information of Oracle
* Corporation. You shall not disclose such confidential and proprietary
* information and shall use it only in accordance with the terms of the
* license agreement you entered into with Oracle.
*
* This notice may not be removed or altered.
*/
#ifndef COH_MAP_EVENT_HPP
#define COH_MAP_EVENT_HPP

#include "coherence/lang.ns"

#include "coherence/util/EventObject.hpp"
#include "coherence/util/Listeners.hpp"

COH_OPEN_NAMESPACE2(coherence,util)

class MapListener;
class ObservableMap;

/**
* An event which indicates that the content of a map has changed:
* <ul>
* <li>an entry has been added</li>
* <li>an entry has been removed</li>
* <li>an entry has been changed</li>
* </ul>
* A MapEvent object is sent as an argument to the MapListener interface
* methods.  NULL values may be provided for the old and the new values.
*
* @author js  2008.06.03
*/
class COH_EXPORT MapEvent
    : public class_spec<MapEvent,
        extends<EventObject> >
    {
    friend class factory<MapEvent>;

    // ----- constructors ---------------------------------------------------

    protected:
        /**
        * Create a MapEvent.
        *
        * @param hMap       the map on which the Event initially occurred
        * @param nId        the events id (ENTRY_INSERTED | ENTRY_UPDATED |
        *                   ENTRY_DELETED)
        * @param vKey       the key into the map
        * @param vValueOld  the old value (for update and delete events)
        * @param vValueNew  the new value (for insert and update events)
        */
        MapEvent(TypedHandle<ObservableMap> hMap, int32_t nId, Object::View vKey,
                Object::View vValueOld, Object::View vValueNew);


    // ----- MapEvent interface ---------------------------------------------

    public:
        /**
        * Return an ObservableMap object on which this event has actually
        * occured.
        *
        * @return an ObservableMap object
        */
        virtual TypedHandle<ObservableMap> getMap() const;

        /**
        * Return this event's id. The event id is one of the ENTRY_*
        * enumerated constants.
        *
        * @return an id
        */
        virtual int32_t getId() const;

        /**
        * Return a key associated with this event.
        *
        * @return a key
        */
        virtual Object::View getKey() const;

        /**
        * Return an old value associated with this event.
        * <p>
        * The old value represents a value deleted from or updated in a map.
        * It is always NULL for "insert" notifications.
        *
        * @return an old value
        */
        virtual Object::View getOldValue() const;

        /**
        * Return a new value associated with this event.
        * <p>
        * The new value represents a new value inserted into or updated in
        * a map. It is always NULL for "delete" notifications.
        *
        * @return a new value
        */
        virtual Object::View getNewValue() const;


    // ----- Object interface -----------------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual void toStream(std::ostream& out) const;


    // ----- helper methods -------------------------------------------------

    public:
        /**
        * Dispatch this event to the specified listeners collection.
        * <p>
        * This call is equivalent to
        * <pre>
        *   dispatch(listeners, true);
        * </pre>
        *
        * @param vListeners the listeners collection
        *
        * @throws ClassCastException if any of the targets is not
        *         an instance of MapListener interface
        */
        virtual void dispatch(Listeners::View vListeners) const;

        /**
        * Dispatch this event to the specified listeners collection.
        *
        * @param vListeners the listeners collection
        * @param fStrict    if true then any RuntimeException thrown by event
        *                   handlers stops all further event processing and
        *                   the exception is re-thrown; if false then all
        *                   exceptions are logged and the process continues
        *
        * @throws ClassCastException if any of the targets is not
        *         an instance of MapListener interface
        */
        virtual void dispatch(Listeners::View vListeners,
                bool fStrict) const;

        /**
        * Dispatch this event to the specified MapListener.
        *
        * @param hListener  the listener
        */
        virtual void dispatch(TypedHandle<MapListener> hListener) const;

        /**
        * Convert an event ID into a human-readable string.
        *
        * @param nId  an event ID, one of the ENTRY_* enumerated values
        *
        * @return a corresponding human-readable string, for example
        *         "inserted"
        */
        static String::View getDescription(int32_t nId);

        using Describable::getDescription;

    // ----- Describable interface ------------------------------------------

    public:
        /**
        * {@inheritDoc}
        */
        virtual void outputDescription(std::ostream& out) const;


    // ----- constants ------------------------------------------------------

    public:
        /**
        * This event indicates that an entry has been added to the map.
        */
        static const int32_t ENTRY_INSERTED = 1;

        /**
        * This event indicates that an entry has been updated in the map.
        */
        static const int32_t ENTRY_UPDATED  = 2;

        /**
        * This event indicates that an entry has been removed from the map.
        */
        static const int32_t ENTRY_DELETED  = 3;


    // ----- data members ---------------------------------------------------

    protected:
        /**
        * The event's id.
        */
        int32_t m_nId;

        /**
        * A key.  This is mutable because subclasses may lazily initialize
        * this value from an accessor.
        */
        mutable MemberView<Object> m_voKey;

        /**
        * A previous value.  May be NULL if not known.  This is mutable
        * because subclasses may lazily initialize this value from an
        * accessor.
        */
        mutable MemberView<Object> m_voValueOld;

        /**
        * A new value.  May be NULL if not known.  This is mutable because
        * subclasses may lazily initialize this value from an accessor.
        */
        mutable MemberView<Object> m_voValueNew;
    };

COH_CLOSE_NAMESPACE2

#endif // COH_MAP_EVENT_HPP

Copyright (c) 2000, 2009, Oracle and/or its affiliates. All rights reserved.