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