00001 /* 00002 * MapTrigger.hpp 00003 * 00004 * Copyright (c) 2000, 2013, 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