---
title:  How Events Work
---

<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements.  See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

Members in your <%=vars.product_name%> distributed system receive cache updates from other members through cache events. The other members can be peers to the member, clients or servers or other distributed systems.

## <a id="how_events_work__section_6C75098DDBB84944ADE57F2088330D5A" class="no-quick-link"></a>Events Features

These are the primary features of <%=vars.product_name%> events:

-   Content-based events
-   Asynchronous event notifications with conflation
-   Synchronous event notifications for low latency
-   High availability through redundant messaging queues
-   Event ordering and once and only-once delivery
-   Distributed event notifications
-   Durable subscriptions
-   Continuous querying

## <a id="how_events_work__section_F5F0E506652940DFBA0D6B7AAA72E3EF" class="no-quick-link"></a>Types of Events

There are two categories of events and event handlers.

-   Cache events in the caching API are used by applications with a cache. Cache events provide detail-level notification for changes to your data. Continuous query events are in this category.
-   Administrative events in the administration API are used by administrative applications without caches.

Both kinds of events can be generated by a single member operation.

**Note:**
You can handle one of these categories of events in a single system member. You cannot handle both cache and administrative events in a single member.

Because <%=vars.product_name%> maintains the order of administrative events and the order of cache events separately, using cache events and administrative events in a single process can cause unexpected results.

## <a id="how_events_work__section_4BCDB22AB927478EBF1035B0DE230DD3" class="no-quick-link"></a>Event Cycle

The following steps describe the event cycle:

1.  An operation begins, such as data put or a cache close.
2.  The operation execution generates these objects:
    -   An object of type `Operation` that describes the method that triggered the event.
    -   An event object that describes the event, such as the member and region where the operation originated.

3.  The event handlers that can handle the event are called and passed the event objects. Different event types require different handler types in different locations. If there is no matching event handler, that does not change the effect of the operation, which happens as usual.
4.  When the handler receives the event, it triggers the handler’s callback method for this event. The callback method can hand off the event object as input to another method. Depending on the type of event handler, the callbacks can be triggered before or after the operation. The timing depends on the event handler, not on the event itself.
    **Note:**
    For transactions, after-operation listeners receive the events after the transaction has committed.

5.  If the operation is distributed, so that it causes follow-on operations in other members, those operations generate their own events, which can be handled by their listeners in the same way.

## <a id="how_events_work__section_E48ECC8A1B39411AA23D17BA0C05517E" class="no-quick-link"></a>Event Objects

Event objects come in several types, depending on the operation. Some operations generate multiple objects of different types. All event objects contain data describing the event, and each event type carries slightly different kinds of data appropriate to its matching operation. An event object is stable. For example, its content does not change if you pass it off to a method on another thread.

For cache events, the event object describes the operation performed in the local cache. If the event originated remotely, it describes the local application of the remote entry operation, not the remote operation itself. The only exception is when the local region has an empty data policy; then the event carries the information for the remote (originating) cache operation.

## <a id="how_events_work__section_2EA59E9F7203433A8AD248C499D61BF4" class="no-quick-link"></a>Event Distribution

After a member processes an event in its local cache, it distributes it to remote caches according to the member's configuration and the configurations of the remote caches. For example, if a client updates its cache, the update is forwarded to the client's server. The server distributes the update to its peers and forwards it to any other clients according to their interest in the data entry. If the server system is part of a multi-site deployment and the data region is configured to use a gateway sender, then the gateway sender also forwards the update to a remote site, where the update is further distributed and propagated.

## <a id="how_events_work__section_C18D3CA923FB427AA01DD811589D63C0" class="no-quick-link"></a>Event Handlers and Region Data Storage

You can configure a region for no local data storage and still send and receive events for the region. Conversely, if you store data in the region, the cache is updated with data from the event regardless of whether you have any event handlers installed.

## <a id="how_events_work__section_22EB4B9E6C4445F898DB64A769780460" class="no-quick-link"></a>Multiple Listeners

When multiple listeners are installed, as can be done with cache listeners, the listeners are invoked sequentially in the order they were added to the region or cache. Listeners are executed one at a time. So, unless you program a listener to pass off processing to another thread, you can use one listener's work in later listeners.

## <a id="how_events_work__section_C4758D7E2CA2498A87315DE903A07AE4" class="no-quick-link"></a>Event Ordering

During a cache operation, event handlers are called at various stages of the operation. Some event handlers are called before a region update and some are called after the region update operation. Depending on the type of event handler being called, the event handler can receive the events in-order or out-of-order in which they are applied on Region.

-   `CacheWriter` and `AsyncEventListener` always receive events in the order in which they are applied on region.
-   `CacheListener` and `CqListener` can receive events in a different order than the order in which they were applied on the region.

**Note:**
An `EntryEvent` contains both the old value and the new value of the entry, which helps to indicate the value that was replaced by the cache operation on a particular key.

-   **[Peer-to-Peer Event Distribution](how_cache_events_work.html)**

    When a region or entry operation is performed, <%=vars.product_name%> distributes the associated events in the distributed system according to system and cache configurations.

-   **[Client-to-Server Event Distribution](how_client_server_distribution_works.html)**

    Clients and servers distribute events according to client activities and according to interest registered by the client in server-side cache changes.

-   **[Multi-Site (WAN) Event Distribution](how_multisite_distribution_works.html)**

    <%=vars.product_name%> distributes a subset of cache events between distributed systems, with a minimum impact on each system's performance. Events are distributed only for regions that you configure to use a gateway sender for distribution.

-   **[List of Event Handlers and Events](list_of_event_handlers_and_events.html)**

    <%=vars.product_name%> provides many types of events and event handlers to help you manage your different data and application needs.


