Cache Notifications (Windows Server AppFabric Caching)

  • Article

Windows Server AppFabric 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 (Windows Server AppFabric Caching).

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.

Note

To use cache notifications, you will have to enable cache notifications on a named cache with the New-Cache or Set-CacheConfig Windows PowerShell commands from the Windows PowerShell-based cache administration tool.

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.

Changes that trigger cache notifications

These cache operations are defined by members of the DataCacheOperations class.

Region Operations

Your application can receive cache notifications when the following cache operations occur on a region:

Item Operations

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.

Note

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.

Notification Scope

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. AppFabric 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.

Cache Notification Scope

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.

Notification Order

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 RegionA.

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.

Note

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.

Polling Interval

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 NotificationProperties property of the DataCacheFactoryConfiguration object.

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 Add a Failure Notification Callback (Windows Server AppFabric Caching)

When the Cache Cluster Is Lost

There is an important distinction between loss of notifications and loss of the cache cluster. If your application loses 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.

Note

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 by 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 Edit Cache Configuration Settings with Windows PowerShell (Windows Server AppFabric Caching).

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 clientNotification element in the XML-based application configuration file or specify your desired interval programmatically with the NotificationsProperties property of the DataCacheFactoryConfiguration object.

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 (Windows Server AppFabric Caching).

See Also

Concepts

Windows Server AppFabric Caching Physical Architecture Diagram
Windows Server AppFabric Caching Logical Architecture Diagram
Developing a Cache Client (Windows Server AppFabric Caching)