00001 /* 00002 * ContinuousQueryCache.hpp 00003 * 00004 * Copyright (c) 2000, 2019, 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_CONTINUOUS_QUERY_CACHE_HPP 00017 #define COH_CONTINUOUS_QUERY_CACHE_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/net/CacheService.hpp" 00022 #include "coherence/net/NamedCache.hpp" 00023 00024 #include "coherence/util/AbstractMap.hpp" 00025 #include "coherence/util/Comparator.hpp" 00026 #include "coherence/util/MapEvent.hpp" 00027 #include "coherence/util/MapIndex.hpp" 00028 #include "coherence/util/MapListener.hpp" 00029 #include "coherence/util/MapListenerSupport.hpp" 00030 #include "coherence/util/MultiplexingMapListener.hpp" 00031 #include "coherence/util/Set.hpp" 00032 #include "coherence/util/Supplier.hpp" 00033 #include "coherence/util/ValueExtractor.hpp" 00034 00035 #include "coherence/util/filter/MapEventFilter.hpp" 00036 00037 COH_OPEN_NAMESPACE3(coherence,net,cache) 00038 00039 using coherence::net::CacheService; 00040 using coherence::net::NamedCache; 00041 using coherence::util::AbstractMap; 00042 using coherence::util::Comparator; 00043 using coherence::util::Filter; 00044 using coherence::util::MapEvent; 00045 using coherence::util::MapIndex; 00046 using coherence::util::MapListener; 00047 using coherence::util::MapListenerSupport; 00048 using coherence::util::MultiplexingMapListener; 00049 using coherence::util::Set; 00050 using coherence::util::Supplier; 00051 using coherence::util::ValueExtractor; 00052 using coherence::util::filter::MapEventFilter; 00053 00054 /** 00055 * Create a materialized view of a NamedCache using the Coherence 00056 * <i>Continuous Query</i> capability. 00057 * 00058 * @author tb, js 2008.07.23 00059 */ 00060 class COH_EXPORT ContinuousQueryCache 00061 : public class_spec<ContinuousQueryCache, 00062 extends<AbstractMap>, 00063 implements<NamedCache> > 00064 { 00065 friend class factory<ContinuousQueryCache>; 00066 00067 // ----- constructors --------------------------------------------------- 00068 00069 protected: 00070 /** 00071 * Create a materialized view of a NamedCache using a Filter. A 00072 * materialized view is an implementation of <i>Continuous Query</i> 00073 * exposed through the standard NamedCache API. This constructor 00074 * allows a client to receive all events, including those that result 00075 * from the initial population of the ContinuousQueryCache. In other 00076 * words, all contents of the ContinuousQueryCache will be delivered 00077 * to the listener as a sequence of events, including those items that 00078 * already exist in the underlying (unfiltered) cache. 00079 * 00080 * @param hCache the NamedCache to create a view of 00081 * @param vFilter the Filter that defines the view 00082 * @param fCacheValues pass true to cache both the keys and values of 00083 * the materialized view locally, or false to 00084 * only cache the keys 00085 * @param hListener an initial MapListener that will receive all 00086 * the events from the ContinuousQueryCache, 00087 * including those corresponding to its initial 00088 * population 00089 * @param vTransformer the transformer that should be used to convert 00090 * values from the underlying cache before storing 00091 * them locally 00092 */ 00093 ContinuousQueryCache(NamedCache::Handle hCache, 00094 Filter::View vFilter, bool fCacheValues = false, 00095 MapListener::Handle hListener = NULL, 00096 ValueExtractor::View vTransformer = NULL); 00097 00098 /** 00099 * Create a materialized view of a NamedCache using a Filter. A 00100 * materialized view is an implementation of <i>Continuous Query</i> 00101 * exposed through the standard NamedCache API. This constructor 00102 * allows a client to receive all events, including those that result 00103 * from the initial population of the ContinuousQueryCache. In other 00104 * words, all contents of the ContinuousQueryCache will be delivered 00105 * to the listener as a sequence of events, including those items that 00106 * already exist in the underlying (unfiltered) cache. 00107 * 00108 * @param vCacheSupplier the Supplier returning the NamedCache to create 00109 * a view of 00110 * @param vFilter the Filter that defines the view 00111 * @param fCacheValues pass true to cache both the keys and values of 00112 * the materialized view locally, or false to 00113 * only cache the keys 00114 * @param hListener an initial MapListener that will receive all 00115 * the events from the ContinuousQueryCache, 00116 * including those corresponding to its initial 00117 * population 00118 * @param vTransformer the transformer that should be used to convert 00119 * values from the underlying cache before storing 00120 * them locally 00121 */ 00122 ContinuousQueryCache(Supplier::View vCacheSupplier, 00123 Filter::View vFilter, bool fCacheValues, 00124 MapListener::Handle hListener, 00125 ValueExtractor::View vTransformer); 00126 00127 00128 // ----- accessors ------------------------------------------------------ 00129 00130 public: 00131 /** 00132 * Obtain the NamedCache that this ContinuousQueryCache is based on. 00133 * 00134 * @return the underlying NamedCache 00135 */ 00136 virtual NamedCache::View getCache() const; 00137 00138 /** 00139 * Obtain the NamedCache that this ContinuousQueryCache is based on. 00140 * 00141 * @return the underlying NamedCache 00142 */ 00143 virtual NamedCache::Handle getCache(); 00144 00145 /** 00146 * Obtain the Filter that this ContinuousQueryCache is using to query 00147 * the underlying NamedCache. 00148 * 00149 * @return the Filter that this cache uses to select its contents from 00150 * the underlying NamedCache 00151 */ 00152 virtual Filter::View getFilter() const; 00153 00154 /** 00155 * Obtain the transformer that this ContinuousQueryCache is using to transform 00156 * the results from the underlying cache. 00157 * 00158 * @return the ValueExtractor that this cache uses to transform entries from 00159 * the underlying cache 00160 * 00161 * @since 12.2.1.4 00162 */ 00163 virtual ValueExtractor::View getTransformer() const; 00164 00165 /** 00166 * Obtain the MapListener provided at construction time for 00167 * this ContinuousQueryCache. 00168 * 00169 * @return the MapListener provided at construction time for 00170 * this ContinuousQueryCache 00171 * 00172 * @since 12.2.1.4 00173 */ 00174 virtual MapListener::View getMapListener() const; 00175 00176 /** 00177 * Determine if this ContinuousQueryCache caches values locally. 00178 * 00179 * @return true if this object caches values locally, and false if it 00180 * relies on the underlying NamedCache 00181 */ 00182 virtual bool isCacheValues() const; 00183 00184 /** 00185 * Modify the local-caching option for the ContinuousQueryCache. By 00186 * changing this value from <tt>false</tt> to <tt>true</tt>, the 00187 * ContinuousQueryCache will fully realize its contents locally and 00188 * maintain them coherently in a manner analogous to the Coherence 00189 * NearCache. By changing this value from <tt>true</tt> to 00190 * <tt>false</tt>, the ContinuousQueryCache will discard its locally 00191 * cached data and rely on the underlying NamedCache. 00192 * 00193 * @param fCacheValues pass true to enable local caching, or false to 00194 * disable it 00195 */ 00196 virtual void setCacheValues(bool fCacheValues); 00197 00198 /** 00199 * Determine if this ContinuousQueryCache disallows data modification 00200 * operations. 00201 * 00202 * @return true if this ContinuousQueryCache has been configured as 00203 * read-only 00204 */ 00205 virtual bool isReadOnly() const; 00206 00207 /** 00208 * Modify the read-only option for the ContinuousQueryCache. Note that 00209 * the cache can be made read-only, but the opposite (making it 00210 * mutable) is explicitly disallowed. 00211 * 00212 * @param fReadOnly pass true to prohibit clients from making 00213 * modifications to this cache 00214 */ 00215 virtual void setReadOnly(bool fReadOnly); 00216 00217 /** 00218 * Obtain the state of the ContinuousQueryCache. 00219 * 00220 * @return one of the STATE_ enums 00221 */ 00222 virtual int32_t getState() const; 00223 00224 /** 00225 * Return a reconnection interval (in milliseconds). This value 00226 * indicates how often the ContinuousQueryCache should attempt to 00227 * re-connect with the underlying [clustered] cache in case the 00228 * connection is severed. 00229 * 00230 * @return a reconnection interval (in milliseconds) 00231 */ 00232 virtual int64_t getReconnectInterval() const; 00233 00234 /** 00235 * Specify a reconnection interval (in milliseconds). This value 00236 * indicates how often the ContinuousQueryCache should attempt to 00237 * re-connect with the underlying [clustered] cache in case the 00238 * connection is severed. 00239 * 00240 * @param cReconnectMillis reconnection interval (in milliseconds). 00241 * The value of zero means that the ContinuousQueryCache cannot 00242 * be used when not connected. If the value is positive, the 00243 * local content could be accessed (read-only) even if 00244 * connection is severed. 00245 */ 00246 virtual void setReconnectInterval(int64_t cReconnectMillis); 00247 00248 /** 00249 * Return the Supplier used to provide the name of this ContinuousQueryCache. 00250 * 00251 * @return the Supplier used to provide the name of this ContinuousQueryCache 00252 * 00253 * @since 12.2.1.4 00254 */ 00255 virtual Supplier::View getCacheNameSupplier() const; 00256 00257 /** 00258 * Provide the Supplier used to provide the name of this ContinuousQueryCache. 00259 * 00260 * @param vCacheNameSupplier the Supplier used to provide the name of this ContinuousQueryCache 00261 * 00262 * @since 12.2.1.4 00263 */ 00264 virtual void setCacheNameSupplier(Supplier::View vCacheNameSupplier); 00265 00266 protected: 00267 /** 00268 * Create the internal cache used by the ContinuousQueryCache. 00269 * 00270 * @return a new ObservableMap that will represent the materialized 00271 * view of the ContinuousQueryCache 00272 */ 00273 virtual ObservableMap::Handle instantiateInternalCache() const; 00274 00275 /** 00276 * Obtain a reference to the internal cache. The internal cache 00277 * maintains all of the keys in the ContinuousQueryCache, and if 00278 * isCacheValues()is true, it also maintains the up-to-date values 00279 * corresponding to those keys. 00280 * 00281 * @return the internal cache that represents the materialized view of 00282 * the ContinuousQueryCache 00283 */ 00284 virtual ObservableMap::View getInternalCache() const; 00285 00286 /** 00287 * Obtain a reference to the internal cache. The internal cache 00288 * maintains all of the keys in the ContinuousQueryCache, and if 00289 * isCacheValues()is true, it also maintains the up-to-date values 00290 * corresponding to those keys. 00291 * 00292 * @return the internal cache that represents the materialized view of 00293 * the ContinuousQueryCache 00294 */ 00295 virtual ObservableMap::Handle getInternalCache(); 00296 00297 /** 00298 * Determine if the ContinuousQueryCache has any listeners that cannot 00299 * be served by this Map listening to lite events. 00300 * 00301 * @return true iff there is at least one listener 00302 */ 00303 virtual bool isObserved() const; 00304 00305 /** 00306 * Specify whether the ContinuousQueryCache has any listeners that 00307 * cannot be served by this Map listening to lite events. 00308 * 00309 * @param fObserved true iff there is at least one listener 00310 */ 00311 virtual void setObserved(bool fObserved); 00312 00313 /** 00314 * Change the state of the ContinuousQueryCache. 00315 * 00316 * @param nState one of the STATE_ enums 00317 */ 00318 virtual void changeState(int32_t nState) const; 00319 00320 00321 // ----- Map interface -------------------------------------------------- 00322 00323 public: 00324 /** 00325 * {@inheritDoc} 00326 */ 00327 virtual Object::Holder get(Object::View vKey) const; 00328 00329 /** 00330 * {@inheritDoc} 00331 */ 00332 using Map::get; 00333 00334 /** 00335 * {@inheritDoc} 00336 */ 00337 virtual Object::Holder put(Object::View vKey, Object::Holder ohValue); 00338 00339 /** 00340 * {@inheritDoc} 00341 */ 00342 virtual Object::Holder remove(Object::View vKey); 00343 using Map::remove; 00344 00345 /** 00346 * {@inheritDoc} 00347 */ 00348 virtual void putAll(Map::View vMap); 00349 00350 /** 00351 * {@inheritDoc} 00352 */ 00353 virtual void clear(); 00354 00355 /** 00356 * {@inheritDoc} 00357 */ 00358 virtual bool containsKey(Object::View vKey) const; 00359 00360 /** 00361 * {@inheritDoc} 00362 */ 00363 virtual Set::View keySet() const; 00364 00365 /** 00366 * {@inheritDoc} 00367 */ 00368 virtual Set::Handle keySet(); 00369 00370 /** 00371 * {@inheritDoc} 00372 */ 00373 virtual Set::View entrySet() const; 00374 00375 /** 00376 * {@inheritDoc} 00377 */ 00378 virtual Set::Handle entrySet(); 00379 00380 /** 00381 * {@inheritDoc} 00382 */ 00383 virtual size32_t size() const; 00384 00385 00386 // ----- CacheMap interface --------------------------------------------- 00387 00388 public: 00389 /** 00390 * {@inheritDoc} 00391 */ 00392 virtual Map::View getAll(Collection::View vKeys) const; 00393 00394 /** 00395 * {@inheritDoc} 00396 */ 00397 virtual Object::Holder put(Object::View vKey, 00398 Object::Holder ohValue, int64_t cMillis); 00399 00400 00401 // ----- ObservableMap interface ---------------------------------------- 00402 00403 public: 00404 /** 00405 * {@inheritDoc} 00406 */ 00407 virtual void addKeyListener(MapListener::Handle hListener, 00408 Object::View vKey, bool fLite); 00409 00410 /** 00411 * {@inheritDoc} 00412 */ 00413 virtual void removeKeyListener(MapListener::Handle hListener, 00414 Object::View vKey); 00415 00416 /** 00417 * {@inheritDoc} 00418 */ 00419 virtual void addMapListener(MapListener::Handle hListener); 00420 00421 /** 00422 * {@inheritDoc} 00423 */ 00424 virtual void removeMapListener(MapListener::Handle hListener); 00425 00426 /** 00427 * {@inheritDoc} 00428 */ 00429 virtual void addFilterListener(MapListener::Handle hListener, 00430 Filter::View vFilter = NULL, bool fLite = false); 00431 00432 /** 00433 * {@inheritDoc} 00434 */ 00435 virtual void removeFilterListener(MapListener::Handle hListener, 00436 Filter::View vFilter = NULL); 00437 00438 00439 // ----- QueryMap interface --------------------------------------------- 00440 00441 public: 00442 /** 00443 * {@inheritDoc} 00444 */ 00445 virtual Set::View keySet(Filter::View vFilter) const; 00446 00447 /** 00448 * {@inheritDoc} 00449 */ 00450 virtual Set::View entrySet(Filter::View vFilter) const; 00451 00452 /** 00453 * {@inheritDoc} 00454 */ 00455 virtual Set::View entrySet(Filter::View vFilter, 00456 Comparator::View vComparator) const; 00457 00458 /** 00459 * If isCacheValues is true, the index will be created locally as well as 00460 * on the NamedCache this ContinuousQueryCache wraps, otherwise, the index will be 00461 * created on the wrapped NamedCache only. 00462 * 00463 * See QueryMap::addIndex(ValueExtractor, bool, Comparator) 00464 */ 00465 virtual void addIndex(ValueExtractor::View vExtractor, 00466 bool fOrdered, Comparator::View vComparator); 00467 00468 /** 00469 * If isCacheValues() is true, the index will be removed locally, however, this call 00470 * will not cause the index on the NamedCache this ContinuousQueryCache wraps. 00471 * Developers must remove the index on the wrapped cache manually. 00472 * 00473 * @see QueryMap::removeIndex(ValueExtractor) 00474 */ 00475 virtual void removeIndex(ValueExtractor::View vExtractor); 00476 00477 00478 // ----- InvocableMap interface ----------------------------------------- 00479 00480 public: 00481 /** 00482 * {@inheritDoc} 00483 */ 00484 virtual Object::Holder invoke(Object::View vKey, 00485 InvocableMap::EntryProcessor::Handle hAgent); 00486 00487 /** 00488 * {@inheritDoc} 00489 */ 00490 virtual Map::View invokeAll(Collection::View vCollKeys, 00491 InvocableMap::EntryProcessor::Handle hAgent); 00492 00493 /** 00494 * {@inheritDoc} 00495 */ 00496 virtual Map::View invokeAll(Filter::View vFilter, 00497 InvocableMap::EntryProcessor::Handle hAgent); 00498 00499 /** 00500 * {@inheritDoc} 00501 */ 00502 virtual Object::Holder aggregate(Collection::View vCollKeys, 00503 InvocableMap::EntryAggregator::Handle hAgent) const; 00504 00505 /** 00506 * {@inheritDoc} 00507 */ 00508 virtual Object::Holder aggregate(Filter::View vFilter, 00509 InvocableMap::EntryAggregator::Handle hAgent) const; 00510 00511 00512 // ----- ConcurrentMap interface ---------------------------------------- 00513 00514 public: 00515 /** 00516 * {@inheritDoc} 00517 */ 00518 virtual bool lock(Object::View vKey, int64_t cWait) const; 00519 00520 /** 00521 * {@inheritDoc} 00522 */ 00523 virtual bool lock(Object::View vKey) const; 00524 00525 /** 00526 * {@inheritDoc} 00527 */ 00528 virtual bool unlock(Object::View vKey) const; 00529 00530 00531 // ----- NamedCache interface ------------------------------------------- 00532 00533 public: 00534 /** 00535 * {@inheritDoc} 00536 */ 00537 virtual String::View getCacheName() const; 00538 00539 /** 00540 * {@inheritDoc} 00541 */ 00542 virtual CacheService::Handle getCacheService(); 00543 00544 /** 00545 * {@inheritDoc} 00546 */ 00547 virtual CacheService::View getCacheService() const; 00548 00549 /** 00550 * {@inheritDoc} 00551 */ 00552 virtual bool isActive() const; 00553 00554 /** 00555 * {@inheritDoc} 00556 */ 00557 virtual void release(); 00558 00559 /** 00560 * {@inheritDoc} 00561 */ 00562 virtual void destroy(); 00563 00564 /** 00565 * {@inheritDoc} 00566 */ 00567 virtual void truncate(); 00568 00569 00570 // ----- inner class: AsynchronousEvent --------------------------------- 00571 00572 public: 00573 /** 00574 * Encapsulates an event and a listener that are to be dispatched 00575 * asynchronously. 00576 */ 00577 class AsynchronousEvent 00578 : public class_spec<AsynchronousEvent> 00579 { 00580 friend class factory<AsynchronousEvent>; 00581 00582 // ----- constructors/destructor ---------------------------- 00583 00584 protected: 00585 /** 00586 * @internal 00587 */ 00588 AsynchronousEvent(MapEvent::Handle hEvent, 00589 MapListener::Handle hListener); 00590 00591 // ----- AsynchronousEvent interface ------------------------- 00592 00593 public: 00594 /** 00595 * Dispatch the event. 00596 */ 00597 virtual void dispatch(); 00598 00599 // ----- data members --------------------------------------- 00600 00601 protected: 00602 /** 00603 * The event to dispatch. 00604 */ 00605 FinalHandle<MapEvent> f_hEvent; 00606 00607 /** 00608 * The listener to receive the event. 00609 */ 00610 FinalHandle<MapListener> f_hListener; 00611 }; 00612 00613 00614 // ----- inner interface: EventQueueDaemon ------------------------------ 00615 00616 public: 00617 /** 00618 * Daemon thread used to dispatch messages asynchronously. 00619 */ 00620 class COH_EXPORT TaskDaemon 00621 : public interface_spec<TaskDaemon> 00622 { 00623 public: 00624 /** 00625 * Schedule an event for asynchronous processing 00626 * 00627 * @param hEvent the event to dispatch 00628 */ 00629 virtual void scheduleDispatch( 00630 AsynchronousEvent::Handle hEvent) = 0; 00631 00632 /** 00633 * Start the daemon thread. 00634 */ 00635 virtual void start() = 0; 00636 00637 /** 00638 * Stop the daemon thread. 00639 */ 00640 virtual void stop() = 0; 00641 }; 00642 00643 00644 // ----- internal ------------------------------------------------------- 00645 00646 protected: 00647 /** 00648 * Return a filter which merges the ContinousQueueCache's filter with 00649 * the supplied filter. 00650 * 00651 * @param vFilter the filter to merge with this cache's filter 00652 * 00653 * @return the merged filter 00654 */ 00655 virtual Filter::View mergeFilter(Filter::View vFilter) const; 00656 00657 /** 00658 * Check the read-only setting to verify that the cache is NOT 00659 * read-only. 00660 * 00661 * @throws IllegalStateException if the ContinuousQueryCache is 00662 * read-only 00663 */ 00664 virtual void checkReadOnly() const; 00665 00666 /** 00667 * Check the passed value to verify that it does belong in this 00668 * ContinuousQueryCache. 00669 * 00670 * @param vEntry a key value pair to check. 00671 * 00672 * @throws IllegalArgumentException if the entry does not belong in 00673 * this ContinuousQueryCache (based on the cache's filter) 00674 */ 00675 virtual void checkEntry(Map::Entry::View vEntry); 00676 00677 /** 00678 * Check the passed value to verify that it does belong in this 00679 * ContinuousQueryCache. 00680 * 00681 * @param vKey the key for the entry 00682 * @param ohValue the value for the entry 00683 * 00684 * @throws IllegalArgumentException if the entry does not belong in 00685 * this ContinuousQueryCache (based on the cache's filter) 00686 */ 00687 virtual void checkEntry(Object::View vKey, Object::Holder ohValue); 00688 00689 /** 00690 * Set up the listeners that keep the ContinuousQueryCache up-to-date. 00691 * 00692 * @param fReload pass true to force a data reload 00693 */ 00694 virtual void configureSynchronization(bool fReload) const; 00695 00696 /** 00697 * Wrap specified MapEventFilter with a MapEventTransformerFilter that 00698 * will either transform cache value using transformer defined for this 00699 * ContinuousQueryCache, or remove the old value from the event using 00700 * SemiLiteEventTransformer, if no transformer is defined for this CQC. 00701 * 00702 * @param filterAdd add filter to wrap 00703 * 00704 * @return MapEventTransformerFilter that wraps specified add filter 00705 * 00706 * @since Coherence 12.1.2 00707 */ 00708 virtual Filter::View createTransformerFilter( 00709 MapEventFilter::View vFilterAdd) const; 00710 00711 /** 00712 * Ensure that the ContinousQueryCache listeners have been registered 00713 * and its content synchronized with the underlying NamedCache. 00714 * 00715 * @param fReload the value to pass to the #configureSynchronization 00716 * method if the ContinousQueryCache needs to be 00717 * configured and synchronized 00718 */ 00719 virtual void ensureSynchronized(bool fReload) const; 00720 00721 /** 00722 * Called when an event has occurred. Allows the key to be logged as 00723 * requiring deferred synchronization if the event occurs during the 00724 * configuration or population of the ContinuousQueryCache. 00725 * 00726 * @param vKey the key that the event is related to 00727 * 00728 * @return true if the event processing has been deferred 00729 */ 00730 virtual bool isEventDeferred(Object::View vKey) const; 00731 00732 /** 00733 * Removes the mapping for this key from this map if present. This 00734 * method exists to allow sub-classes to optmiize remove 00735 * functionalitly for situations in which the original value is not 00736 * required. 00737 * 00738 * @param vKey key whose mapping is to be removed from the map 00739 * 00740 * @return true iff the Map changed as the result of this operation 00741 */ 00742 virtual bool removeBlind(Object::View vKey); 00743 00744 /** 00745 * Obtain a set of keys that are represented by this Map. 00746 * 00747 * @return an internal Set of keys that are contained by this Map 00748 */ 00749 virtual Set::View getInternalKeySet() const; 00750 00751 /** 00752 * Return the underlying cache. 00753 * 00754 * @return the underlying cache 00755 */ 00756 virtual NamedCache::Handle getCacheInternal() const; 00757 00758 /** 00759 * Factory Method: Instantiate a MapListener for adding items to the 00760 * query, and (if there are listeners on the ContinuousQueryCache) for 00761 * dispatching inserts and updates. 00762 * 00763 * @return a new MapListener that will add items to and update items 00764 * in the ContinuousQueryCache 00765 */ 00766 virtual MapListener::Handle instantiateAddListener() const; 00767 00768 /** 00769 * Factory Method: Instantiate a MapListener for evicting items from 00770 * the query. 00771 * 00772 * @return a new MapListener that will listen to all events that will 00773 * remove items from the ContinuousQueryCache 00774 */ 00775 virtual MapListener::Handle instantiateRemoveListener() const; 00776 00777 /** 00778 * Instantiate and register a MemberListener with the underlying 00779 * caches's service. 00780 * 00781 * The primary goal of that listener is invalidation of the front map 00782 * in case of the service [automatic] restart. 00783 */ 00784 virtual void registerServiceListener() const; 00785 00786 /** 00787 * Unregister underlying caches's service member listener. 00788 */ 00789 virtual void unregisterServiceListener() const; 00790 00791 /** 00792 * Create and initialize this ContinuousQueryCache's (if not already present) internal cache. 00793 * This method is called by configureSynchronization, as such, it shouldn't be called 00794 * directly. Use getInternalCache. 00795 * 00796 * @return the ObservableMap functioning as this ContinuousQueryCache's 00797 * internal cache 00798 * 00799 * @since 12.2.1.4 00800 */ 00801 virtual ObservableMap::Handle ensureInternalCache() const; 00802 00803 /** 00804 * Verify that the non-existent keys are NOT present in the 00805 * underlying cache (assumption is most keys in the collection are 00806 * already in the ContinuousQueryCache). 00807 * 00808 * @param vCollKeys the keys to check the underlying cache against. 00809 * 00810 * @return the NamedCache 00811 * 00812 * @throws coherence::lang::IllegalStateException if any of the keys in 00813 * collKeys doesn't exist within the ContinuousQueryCache 00814 * 00815 * @since 12.2.1.4 00816 */ 00817 virtual void ensureSaneCache(Collection::View vCollKeys) const; 00818 00819 /** 00820 * Instantiate and register a NamedCacheDeactivationListener with the underlying cache 00821 * service. 00822 * 00823 * The primary goal of that listener is invalidation of the named cache 00824 * in case the named caches is destroyed / truncated. 00825 * 00826 * @since 12.2.1.4 00827 */ 00828 virtual void registerDeactivationListener() const; 00829 00830 /** 00831 * Unregister underlying cache service member listener. 00832 * 00833 * @since 12.2.1.4 00834 */ 00835 virtual void unregisterDeactivationListener() const; 00836 00837 /** 00838 * Release the listeners. 00839 * 00840 * @since 12.2.1.4 00841 */ 00842 virtual void releaseListeners() const; 00843 00844 /** 00845 * Factory Method: Instantiate a listener on the internal map that 00846 * will direct events to the passed listener, either synchronously or 00847 * asynchronously as appropriate. 00848 * 00849 * @param hListener the listener to route to 00850 * @param fLite true to indicate that the MapEvent objects do 00851 * not have to include the OldValue and NewValue 00852 * property values in order to allow optimizations 00853 * 00854 * @return a new EventRouter specific to the passed listener 00855 */ 00856 virtual MultiplexingMapListener::Handle instantiateEventRouter( 00857 MapListener::Handle hListener, bool fLite) const; 00858 00859 /** 00860 * Create a self-processing event queue. 00861 * 00862 * @return a QueueProcessor onto which events can be placed in order 00863 * to be dispatched asynchronously 00864 */ 00865 virtual TaskDaemon::Handle instantiateEventQueue() const; 00866 00867 /** 00868 * Obtain this ContinuousQueryCache's event queue. 00869 * 00870 * @return the event queue that this ContinuousQueryCache uses to 00871 * dispatch its events to its non-synchronous listeners 00872 */ 00873 virtual TaskDaemon::Handle getEventQueue() const; 00874 00875 /** 00876 * Obtain the existing event queue or create one if none exists. 00877 * 00878 * @return the event queue that this ContinuousQueryCache uses to 00879 * dispatch its events to its non-synchronous listeners 00880 */ 00881 virtual TaskDaemon::Handle ensureEventQueue() const; 00882 00883 /** 00884 * Shut down running event queue. 00885 */ 00886 virtual void shutdownEventQueue(); 00887 00888 /** 00889 * Create a new key set. 00890 * 00891 * @return the new key set 00892 */ 00893 virtual Set::Handle instantiateKeySet(); 00894 00895 /** 00896 * Create a new EntrySet 00897 * 00898 * @return the new empty set 00899 */ 00900 virtual Set::Handle instantiateEntrySet(); 00901 00902 /** 00903 * Ensure that the map of indexes maintained by this cache exists. 00904 * 00905 * @return the map of indexes. 00906 */ 00907 virtual Map::Handle ensureIndexMap(); 00908 00909 /** 00910 * Get the map of indexes maintained by this cache. 00911 * 00912 * @return the map of indexes. 00913 */ 00914 virtual Map::View getIndexMap() const; 00915 00916 /** 00917 * Get the map of indexes maintained by this cache. 00918 * 00919 * @return the map of indexes. 00920 */ 00921 virtual Map::Handle getIndexMap(); 00922 00923 /** 00924 * Release the the entire index map. 00925 */ 00926 virtual void releaseIndexMap(); 00927 00928 // ----- Object interface ----------------------------------------------- 00929 00930 protected: 00931 /** 00932 * {@inheritDoc} 00933 */ 00934 virtual void onInit(); 00935 00936 00937 // ----- constants ------------------------------------------------------ 00938 00939 public: 00940 /** 00941 * State: Disconnected state. The content of the ContinousQueryCache is 00942 * not fully synchronized with the underlying [clustered] cache. If the 00943 * value of the ReconnectInterval property is zero, it must be 00944 * configured (synchronized) before it can be used. 00945 */ 00946 static const int32_t state_disconnected = 0; 00947 00948 /** 00949 * State: The ContinuousQueryCache is configuring or re-configuring its 00950 * listeners and content. 00951 */ 00952 static const int32_t state_configuring = 1; 00953 00954 /** 00955 * State: The ContinousQueryCache has been configured. 00956 */ 00957 static const int32_t state_configured = 2; 00958 00959 /** 00960 * State: The ContinousQueryCache has been configured and fully 00961 * synchronized. 00962 */ 00963 static const int32_t state_synchronized = 3; 00964 00965 00966 // ----- data members --------------------------------------------------- 00967 00968 protected: 00969 /** 00970 * The underlying NamedCache object. 00971 */ 00972 mutable MemberHandle<NamedCache> m_hCache; 00973 00974 /** 00975 * The name of the underlying NamedCache. A copy is kept here because 00976 * the reference to the underlying NamedCache is discarded when this 00977 * cache is released. 00978 */ 00979 FinalView<String> f_vsName; 00980 00981 /** 00982 * The filter that represents the subset of information from the 00983 * underlying NamedCache that this ContinuousQueryCache represents. 00984 */ 00985 FinalView<Filter> f_vFilter; 00986 00987 /** 00988 * The option of whether or not to locally cache values. 00989 */ 00990 bool m_fCacheValues; 00991 00992 /** 00993 * The option to disallow modifications through this 00994 * ContinuousQueryCache interface. 00995 */ 00996 bool m_fReadOnly; 00997 00998 /** 00999 * The interval (in milliseconds) that indicates how often the 01000 * ContinuousQueryCache should attempt to synchronize its content with 01001 * the underlying cache in case the connection is severed. 01002 */ 01003 int64_t m_cReconnectMillis; 01004 01005 /** 01006 * The timestamp when the synchronization was last attempted. 01007 */ 01008 mutable Volatile<int64_t> m_ldtConnectionTimestamp; 01009 01010 /** 01011 * The keys that are in this ContinuousQueryCache, and (if 01012 * m_fCacheValues is true) the corresponding values as well. 01013 */ 01014 mutable MemberHandle<ObservableMap> m_hMapLocal; 01015 01016 /** 01017 * State of the ContinousQueryCache. One of the STATE_* enums. 01018 */ 01019 mutable Volatile<int32_t> m_nState; 01020 01021 /** 01022 * While the ContinuousQueryCache is configuring or re-configuring its 01023 * listeners and content, any events that are received must be logged 01024 * to ensure that the corresponding content is in sync. 01025 */ 01026 mutable MemberHandle<Map> m_hMapSyncReq; 01027 01028 /** 01029 * The event queue for this ContinuousQueryCache. 01030 */ 01031 mutable MemberHandle<TaskDaemon> m_hTaskQueue; 01032 01033 /** 01034 * Keeps track of whether the ContinuousQueryCache has listeners that 01035 * require this cache to cache values. 01036 */ 01037 bool m_fListeners; 01038 01039 /** 01040 * The MapEventFilter that uses the ContinuousQueryCache's filter to 01041 * select events that would add elements to this cache's contents. 01042 */ 01043 mutable MemberView<MapEventFilter> m_vFilterAdd; 01044 01045 /** 01046 * The MapEventFilter that uses the ContinuousQueryCache's filter to 01047 * select events that would remove elements from this cache's contents. 01048 */ 01049 mutable MemberView<MapEventFilter> m_vFilterRemove; 01050 01051 /** 01052 * The listener that gets information about what should be in this 01053 * cache. 01054 */ 01055 mutable WeakHandle<MapListener> m_whListenerAdd; 01056 01057 /** 01058 * The listener that gets information about what should be thrown out 01059 * of this cache. 01060 */ 01061 mutable WeakHandle<MapListener> m_whListenerRemove; 01062 01063 /** 01064 * The cache service MemberListener for the underlying NamedCache. 01065 */ 01066 mutable WeakHandle<MemberListener> m_whListenerService; 01067 01068 /* 01069 * The initial MapListener that will receive all the events from the 01070 * ContinuousQueryCache, including those corresponding to its initial 01071 * population. 01072 */ 01073 mutable MemberHandle<MapListener> m_hListener; 01074 01075 /** 01076 * The transformer that should be used to convert values from the 01077 * underlying cache. 01078 */ 01079 FinalView<ValueExtractor> f_vTransformer; 01080 01081 /** 01082 * The map of indexes maintained by this cache. The keys of the Map are 01083 * ValueExtractor objects, and for each key, the corresponding value 01084 * stored in the Map is a MapIndex object. 01085 */ 01086 FinalHandle<Map> f_hMapIndex; 01087 01088 /** 01089 * KeySet backed by this cache 01090 */ 01091 FinalHandle<Set> f_hSetKeys; 01092 01093 /** 01094 * EntrySet backed by this cache 01095 */ 01096 FinalHandle<Set> f_hSetEntries; 01097 01098 /** 01099 * The Supplier of the NamedCache to create a view of. The Supplier must return 01100 * a new instance every time the supplier's get() method is called. 01101 * 01102 * @since 12.2.1.4 01103 */ 01104 FinalView<Supplier> f_vCacheSupplier; 01105 01106 /** 01107 * The optional supplier to obtain this cache's name. 01108 * 01109 * @since 12.2.1.4 01110 */ 01111 MemberView<Supplier> m_vCacheNameSupplier; 01112 01113 /** 01114 * The NamedCache deactivation listener. 01115 * 01116 * @since 12.2.1.4 01117 */ 01118 mutable MemberHandle<MapListener> m_hListenerDeactivation; 01119 01120 01121 // ----- friends -------------------------------------------------------- 01122 01123 friend class AddListener; 01124 friend class RemoveListener; 01125 friend class ServiceListener; 01126 friend class EventRouter; 01127 friend class KeySet; 01128 friend class EntrySet; 01129 friend class KeySetMuterator; 01130 friend class EntrySetIterator; 01131 friend class DeactivationListener; 01132 }; 01133 01134 COH_CLOSE_NAMESPACE3 01135 01136 #endif // COH_CONTINUOUS_QUERY_CACHE_HPP 01137