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

- Main Page
- Namespaces
- Classes
- Files

# coherence/util/MapTrigger.hpp

    00001 /*
    00002 * MapTrigger.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_TRIGGER_HPP
    00017 #define COH_MAP_TRIGGER_HPP
    00018
    00019 #include "coherence/lang.ns"
    00020
    00021 #include "coherence/util/InvocableMap.hpp"
    00022
    00023 COH_OPEN_NAMESPACE2(coherence,util)
    00024
    00025
    00026 /**
    00027 * MapTrigger represents a functional agent that allows to validate, reject or
    00028 * modify mutating operations against an underlying map. The trigger operates
    00029 * on an Entry object that represents a pending mutation that is about to be
    00030 * committed to the underlying map. A MapTrigger could be registered with any
    00031 * ObservableMap using the MapTriggerListener class:
    00032 * <pre>
    00033 *   NamedCache::Handle hCache = CacheFactory->getCache(vsCacheName);
    00034 *   MapTrigger::View vTrigger =  MyCustomTrigger::create();
    00035 *   hCache->addMapListener(MapTriggerListener::create(vTrigger));
    00036 * </pre>
    00037 * <b>Note:</b> In a clustered environment, MapTrigger registration process
    00038 * requires triggers to be pofable and providing a non-default
    00039 * implementation of the hashCode() and equals() methods.
    00040 * Failure to do so may result in duplicate registration and a redundant entry
    00041 * processing by equivalent, but "not equal" MapTrigger objects.
    00042 *
    00043 * @see coherence::util::filter::FilterTrigger
    00044 *
    00045 * @author djl  2008.05.22
    00046 */
    00047 class COH_EXPORT MapTrigger
    00048     : public interface_spec<MapTrigger>
    00049     {
    00050     // ----- inner interface: Entry -----------------------------------------
    00051
    00052     public:
    00053         /**
    00054         * A MapTrigger Entry represents a pending change to an Entry that is
    00055         * about to committed to the underlying Map. The methods inherited
    00056         * from InvocableMap::Entry provide both the pending state and the
    00057         * ability to alter that state. The original state of the Entry can be
    00058         * obtained usingthe #getOriginalValue() and #isOriginalPresent
    00059         * methods.
    00060         */
    00061         class COH_EXPORT Entry
    00062             : public interface_spec<Entry,
    00063                 implements<InvocableMap::Entry> >
    00064             {
    00065             // ----- MapTrigger::Entry interface ----------------------------
    00066
    00067             public:
    00068                 /**
    00069                 * Determine the value that existed before the start of the
    00070                 * mutating operation that is being evaluated by the trigger.
    00071                 *
    00072                 * @return the original value corresponding to this Entry; may
    00073                 *         be null if the value is null or if the Entry did
    00074                 *         not exist in the Map
    00075                 */
    00076                 virtual Object::View getOriginalValue() const = 0;
    00077
    00078                 /**
    00079                 * Determine whether or not the Entry existed before the start
    00080                 * of thenmutating operation that is being evaluated by the
    00081                 * trigger.
    00082                 *
    00083                 * @return true iff this Entry was existent in the containing
    00084                 *         Map
    00085                 */
    00086                 virtual bool isOriginalPresent() const = 0;
    00087             };
    00088
    00089     // ----- MapTrigger interface -------------------------------------------
    00090
    00091     public:
    00092         /**
    00093         * This method is called before the result of a mutating operation
    00094         * represented by the specified Entry object is committed into the
    00095         * underlying map.
    00096         *
    00097         * An implementation of this method can evaluate the change by
    00098         * analyzing the original and the new value, and can perform any of
    00099         * the following:
    00100         * <ul>
    00101         *   <li> override the requested change by calling Entry#setValue
    00102         *        with a different value;
    00103         *   <li> undo the pending change by resetting the entry value to the
    00104         *        original value obtained from Entry#getOriginalValue;
    00105         *   <li> remove the entry from the underlying map by calling
    00106         *        Entry#remove;
    00107         *   <li> reject the pending change by throwing a RuntimeException,
    00108         *        which will prevent any changes from being committed, and
    00109         *        will result in the exception being thrown from the operation
    00110         *        that attempted to modify the map; or
    00111         *   <li> do nothing, thus allowing the pending change to be committed
    00112         *        to the underlying map.
    00113         * </ul>
    00114         *
    00115         * @param vEntry  a Entry object that represents the pending change to
    00116         *                be committed to the map, as well as the original
    00117         *                state of the Entry
    00118         */
    00119         virtual void process(MapTrigger::Entry::Handle vEntry) = 0;
    00120     };
    00121
    00122 COH_CLOSE_NAMESPACE2
    00123
    00124 #endif // COH_MAP_TRIGGER_HPP

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