00001 /* 00002 * AbstractKeyBundler.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_ABSTRACT_KEY_BUNDLER_HPP 00017 #define COH_ABSTRACT_KEY_BUNDLER_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/net/cache/AbstractBundler.hpp" 00022 00023 #include "coherence/util/Collection.hpp" 00024 #include "coherence/util/Collections.hpp" 00025 #include "coherence/util/Map.hpp" 00026 #include "coherence/util/Set.hpp" 00027 00028 COH_OPEN_NAMESPACE3(coherence,net,cache) 00029 00030 using coherence::util::Collection; 00031 using coherence::util::Collections; 00032 using coherence::util::Map; 00033 using coherence::util::Set; 00034 00035 /** 00036 * An abstract key-based bundler serves as a base for NamedCache get() and 00037 * remove() operation bundling. 00038 * 00039 * @author gg 2007.01.28 00040 * @author lh 2012.06.05 00041 * @since Coherence 12.1.2 00042 */ 00043 class COH_EXPORT AbstractKeyBundler 00044 : public abstract_spec<AbstractKeyBundler, 00045 extends<AbstractBundler> > 00046 { 00047 // ----- handle definitions (needed for nested classes) ----------------- 00048 00049 public: 00050 typedef this_spec::Handle Handle; 00051 typedef this_spec::View View; 00052 typedef this_spec::Holder Holder; 00053 00054 // ----- constructors --------------------------------------------------- 00055 00056 protected: 00057 /** 00058 * @internal 00059 */ 00060 AbstractKeyBundler(); 00061 00062 private: 00063 /** 00064 * Blocked copy constructor. 00065 */ 00066 AbstractKeyBundler(const AbstractKeyBundler&); 00067 00068 // ----- bundling support ----------------------------------------------- 00069 00070 public: 00071 /** 00072 * Process the specified key in a most optimal way according to the 00073 * bundle settings. 00074 * 00075 * @param vKey the key to process 00076 * 00077 * @return an execution result according to the caller's contract 00078 */ 00079 Object::Holder process(Object::View vKey); 00080 00081 /** 00082 * Process a colKeys of specified items in a most optimal way according to 00083 * the bundle settings. 00084 * 00085 * @param vColKeys the collection of keys to process 00086 * 00087 * @return an execution result according to the caller's contract 00088 */ 00089 Map::View processAll(Collection::View vColKeys); 00090 00091 // ----- subclassing support -------------------------------------------- 00092 00093 /** 00094 * The bundle operation to be performed against a collected set of keys 00095 * by the concrete AbstractKeyBundler implementations. If an exception 00096 * occurs during bundle operation, it could be repeated using singleton sets. 00097 * 00098 * @param vColKeys a key collection to perform the bundled operation for 00099 * 00100 * @return the Map of operation results 00101 */ 00102 virtual Map::View bundle(Collection::View vColKeys) = 0; 00103 00104 /** 00105 * Un-bundle bundled operation. This operation would be used if an exception 00106 * occurs during a bundled operation or if the number of active threads is 00107 * below the {@link #getThreadThreshold() ThreadThreshold} value. 00108 * 00109 * @param ohKey a key to perform the un-bundled operation for 00110 * 00111 * @return the operation result for the specified key, may be NULL 00112 */ 00113 virtual Object::Holder unbundle(Object::View vKey) = 0; 00114 00115 // ----- AbstractBundler methods ------------------------------------ 00116 00117 /** 00118 * {@inheritDoc} 00119 */ 00120 virtual Bundle::Handle instantiateBundle(); 00121 00122 // ----- inner class: Bundle -------------------------------------------- 00123 00124 /** 00125 * Bundle represents a unit of optimized execution. 00126 */ 00127 protected: 00128 class COH_EXPORT Bundle 00129 : public class_spec<Bundle, 00130 extends<AbstractBundler::Bundle> > 00131 { 00132 friend class factory<Bundle>; 00133 00134 // ----- constructors ------------------------------------- 00135 00136 protected: 00137 /** 00138 * Default constructor. 00139 * 00140 * @param hBundler the AbstructBundler 00141 */ 00142 Bundle(AbstractBundler::Handle hBundler); 00143 00144 // ----- bundling support ----------------------------------- 00145 00146 public: 00147 /** 00148 * Add the specified key to the Bundle. 00149 * 00150 * <b>Note:</b> a call to this method must be externally synchronized 00151 * for this Bundle object. 00152 * 00153 * @param ohKey the key to add to this Bundle 00154 * 00155 * @return true if this Bundle was empty prior to this call 00156 */ 00157 virtual bool add(Object::Holder ohKey); 00158 00159 /** 00160 * Add the specified collection of keys to the Bundle. 00161 * 00162 * <b>Note:</b> a call to this method must be externally synchronized 00163 * for this Bundle object. 00164 * 00165 * @param vColKeys the collection of keys to add to this Bundle 00166 * 00167 * @return true if this Bundle was empty prior to this call 00168 */ 00169 virtual bool addAll(Collection::View vColKeys); 00170 00171 /** 00172 * Process the specified key according to this Bundle state. 00173 * 00174 * @param fBurst true if this thread is supposed to perform an actual 00175 * bundled operation (burst); false otherwise 00176 * @param ohKey the key to process 00177 * 00178 * @return an execution result according to the caller's contract 00179 */ 00180 virtual Object::Holder process(bool fBurst, Object::Holder ohKey); 00181 00182 /** 00183 * Process the specified kye collection according to this Bundle state. 00184 * 00185 * @param fBurst true if this thread is supposed to perform an actual 00186 * bundled operation (burst); false otherwise 00187 * @param vColKeys the collection of keys to process 00188 * 00189 * @return an execution result according to the caller's contract 00190 */ 00191 virtual Map::View processAll(bool fBurst, Collection::View vColKeys); 00192 00193 // ----- AbstractBundler::Bundle methods------------------------- 00194 00195 /** 00196 * {@inheritDoc} 00197 */ 00198 virtual int32_t getBundleSize() const; 00199 00200 /** 00201 * {@inheritDoc} 00202 */ 00203 using AbstractBundler::Bundle::ensureResults; 00204 00205 /** 00206 * {@inheritDoc} 00207 */ 00208 virtual void ensureResults(); 00209 00210 /** 00211 * {@inheritDoc} 00212 */ 00213 virtual bool releaseThread(); 00214 00215 // ----- data fields ---------------------------------------- 00216 00217 private: 00218 /** 00219 * This bundle content. 00220 */ 00221 FinalHandle<Set> f_hSetKeys; 00222 00223 /** 00224 * A result of the bundled processing. 00225 */ 00226 MemberView<Map> m_vMapResults; 00227 }; 00228 }; 00229 00230 COH_CLOSE_NAMESPACE3 00231 00232 #endif // COH_ABSTRACT_KEY_BUNDLER_HPP