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