Cache Notifications (Velocity)
[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]
Microsoft project code named "Velocity" offers cache notifications that allow your applications to receive asynchronous notifications when a variety of cache operations occur on the cache cluster. Cache notifications also provide automatic invalidation of locally cached objects. For more information, see Expiration and Eviction (Velocity).
To receive asynchronous cache notifications, add a cache notification callback to your application. When you add the callback, you define the types of cache operations that trigger a cache notification and which method in your application should be called when the specified operations occur. This topic describes the process in detail.
In order to use cache notifications, you will have to enable cache notifications on a named cache with the
Set-CacheConfig PowerShell cmdlets from the PowerShell-based cache administration tool. You also need to configure your application to use a routing client.
Triggering Cache Notifications
As shown in the following figure, changes to both regions and cached objects (referred to as items within the cache) can trigger cache notifications.
These cache operations are defined by members of the DataCacheOperation class.
Your application can receive cache notifications when the following cache operations occur on a region.
CreateRegion: When a region is created in the cache.
ClearRegion: When a region is cleared in the cache.
RemoveRegion: When a region is removed from the cache.
Your application may receive cache notifications when the following cache operations occur on a cached object (referred to as an item within the cache).
AddItem: When an item is added to the cache.
ReplaceItem: When an item is replaced in the cache.
RemoveItem: When an item is removed from the cache.
By themselves, these item operations do not depend on whether they occurred within a region or not. You can choose to limit the notification scope of your callback to a particular region. This is discussed in the Notification Scope section of this document.
Depending on the activity and needs of your application, you may not want to pay attention to the events from every object and region in the whole cache. "Velocity" allows you to narrow the scope of your notifications from the cache level down to the region level and item level. As seen in the following diagram, the notification scope that you select when you add a callback greatly impacts which cache notifications you will receive.
At the cache level, your application may be notified of all cache operations from all objects and regions in the cache. At the region level, your application will be notified only about cache operations from a single region and the objects in it. At the item level, your application will be notified only about cache operations pertaining to a single object.
To specify the notification scope you want, choose one of these three methods to add a cache notification callback:
AddCacheLevelCallback: When you want to be notified of region- and item-based cache operations occurring on all regions and items.
AddRegionLevelCallback: When you want to be notified of region- and item-based cache operations occurring on one specific region.
AddItemLevelCallback: When you want to be notified of item-based cache operations occurring on one specific item.
The order of notifications received by the cache client is guaranteed within the context of a single region. For example, assume that you have created a region named
RegionA. Because all data put in a cache region is limited to the same region, all cache operations that pertain to
RegionA (region-level notification scope) arrive at the cache client in the appropriate order relative to each other. Region and item-based cache operations that occurred on other cache hosts are not guaranteed to arrive in the appropriate order relative to the operations that occurred in
In the interest of performance, the order of notifications involving more than one region or objects that are not stored in the same region cannot be guaranteed.
Version information for item events, in the form of the DataCacheItemVersion object, is passed to the method invoked by the cache notification with the version parameter. This DataCacheItemVersion object corresponds to the version of the object that triggered the item event. By using the CompareTo method, you can compare versions to determine which cache operations came first.
Version comparisons are only meaningful when comparing versions of the same item specified with the same key. It is not possible to deduce order by comparing versions from different keys; the CompareTo method may return a result, but the result is only valid for versions of the same key.
When you use cache notifications, your application checks with the cache cluster at a regular interval to see if any new notifications are available. This interval, called the polling interval, is every 300 seconds by default.
The polling interval is specified in units of seconds in the application configuration settings. To specify a specific interval, you can use the
pollInterval attribute of the
clientNotifications element in the application configuration file. You can also specify a specific polling interval programmatically with the DataCacheFactory constructor.
When Notifications are Lost
Cache hosts can hold only a certain amount of cache operations in memory. It is possible, depending on system load, that some cache clients may not receive notifications before they are truncated in the cache host queues. Cache clients may also miss notifications when data is lost due to a cache server failure while the rest of the cluster remains running. In these cases, your cache client can discover that it has missed some cache notifications by using a failure notification. Your application can add a callback to receive failure notifications by using the AddFailureNotificationCallback method. For more information, see How to: Add a Failure Notification Callback (Velocity).
When the Cache Cluster is Lost
There is an important distinction between loss of notifications and loss of the cache cluster. If your application losses one or more notifications, it can become aware of that loss by means of a failure notification. If the entire cache cluster is stopped, restarted, or otherwise lost, no notifications will be triggered. Instead, your cache client will throw exceptions the next time you attempt to use the cache if it is unable to connect with the cluster.
Cache notifications only report data-related changes to regions and cache items in the cluster; they do not report events of the cluster itself.
Enabling Cache Notifications
The cache notifications feature is configured at the cache level in the cluster configuration settings. As a property of the cache, you can enable it when you first create the cache using the
New-Cache command with the
NotificationsEnabled switch. By default, the cache notifications feature is disabled when you create a new cache. For more information about editing cache configuration settings, see How to: Edit Cache Configuration Settings with PowerShell (Velocity).
No application configuration settings are required to add a callback for receiving cache notifications. You can use the application configuration settings to specify a specific poll interval. By default, the polling interval is 300 seconds. If you want a different duration, use the
clientNotifications element in the XML-based application configuration file or specify your desired interval programmatically with the parameters of the DataCacheFactory constructor.
Using Cache Notifications
After cache notifications have been enabled, there are three tasks related to using cache notifications: adding cache notification callbacks, adding a failure notification callback, and removing cache notification callbacks. The procedures for each of these tasks are described in Using Cache Notifications (Velocity).