org.apache.ignite.events

## Class CacheEvent

- java.lang.Object
- - org.apache.ignite.events.EventAdapter
  - - org.apache.ignite.events.CacheEvent

All Implemented Interfaces:
  Serializable, Comparable<Event>, Event

    public class CacheEvent
    extends EventAdapter

In-memory database (cache) event.

Grid events are used for notification about what happens within the grid. Note that by design Ignite keeps all events generated on the local node locally and it provides APIs for performing a distributed queries across multiple nodes:

- `IgniteEvents.remoteQuery(IgnitePredicate, long, int...)` - asynchronously querying events occurred on the nodes specified, including remote nodes.
- `IgniteEvents.localQuery(IgnitePredicate, int...)` - querying only local events stored on this local node.
- `IgniteEvents.localListen(IgnitePredicate, int...)` - listening to local grid events (events from remote nodes not included).

User can also wait for events using method `IgniteEvents.waitForLocal(IgnitePredicate, int...)`.

# Events and Performance

Note that by default all events in Ignite are enabled and therefore generated and stored by whatever event storage SPI is configured. Ignite can and often does generate thousands events per seconds under the load and therefore it creates a significant additional load on the system. If these events are not needed by the application this load is unnecessary and leads to significant performance degradation.

It is highly recommended to enable only those events that your application logic requires by using `IgniteConfiguration.getIncludeEventTypes()` method in Ignite configuration. Note that certain events are required for Ignite's internal operations and such events will still be generated but not stored by event storage SPI if they are disabled in Ignite configuration.

See Also:
  `EventType.EVT_CACHE_STARTED`, `EventType.EVT_CACHE_STOPPED`, `EventType.EVT_CACHE_NODES_LEFT`, `EventType.EVTS_CACHE_LIFECYCLE`, `EventType.EVT_CACHE_ENTRY_CREATED`, `EventType.EVT_CACHE_ENTRY_DESTROYED`, `EventType.EVT_CACHE_ENTRY_EVICTED`, `EventType.EVT_CACHE_OBJECT_EXPIRED`, `EventType.EVT_CACHE_OBJECT_LOCKED`, `EventType.EVT_CACHE_OBJECT_PUT`, `EventType.EVT_CACHE_OBJECT_READ`, `EventType.EVT_CACHE_OBJECT_REMOVED`, `EventType.EVT_CACHE_OBJECT_UNLOCKED`, `EventType.EVTS_CACHE`, Serialized Form

### Constructor Summary

Constructors
Constructor and Description
`CacheEvent(String cacheName, ClusterNode node, @Nullable ClusterNode evtNode, String msg, int type, int part, boolean near, Object key, IgniteUuid xid, String txLbl, Object lockId, Object newVal, boolean hasNewVal, Object oldVal, boolean hasOldVal, UUID subjId, String cloClsName, String taskName)` Constructs cache event.

### Method Summary

All Methods Instance Methods Concrete Methods
`String` `cacheName()` Gets cache name.
`String` `closureClassName()` Gets closure class name (applicable only for TRANSFORM operations).
`ClusterNode` `eventNode()` Gets node which initiated cache operation or `null` if that node is not available.
`boolean` `hasNewValue()` Gets flag indicating whether cache entry has new value in case if we only have new value in serialized form in which case `newValue()` will return `null`.
`boolean` `hasOldValue()` Gets flag indicating whether cache entry has old value in case if we only have old value in serialized form in which case `oldValue()` will return `null`.
`boolean` `isNear()` Gets flag indicating whether event happened on `near` or `partitioned` cache.
`<K> K` `key()` Gets cache entry associated with event.
`Object` `lockId()` ID of the lock if held or `null` if no lock held.
`Object` `newValue()` Gets new value for this event.
`Object` `oldValue()` Gets old value associated with this event.
`int` `partition()` Gets partition for the event which is the partition the key belongs to.
`String` `shortDisplay()` Gets a shortened version of `toString()` result.
`UUID` `subjectId()` Gets security subject ID initiated this cache event, if security is enabled.
`String` `taskName()` Gets task name if cache event was caused by an operation initiated within task execution.
`String` `toString()`
`String` `txLabel()` Label of surrounding cache transaction or `null` if there either is no surrounding transaction or label was not set.
`IgniteUuid` `xid()` ID of surrounding cache transaction or `null` if there is no surrounding transaction.

### Methods inherited from class org.apache.ignite.events.EventAdapter

`compareTo, equals, hashCode, id, localOrder, message, message, name, node, node, timestamp, type, type`

### Methods inherited from class java.lang.Object

`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

### Constructor Detail

#### CacheEvent

    public CacheEvent(String cacheName,
                      ClusterNode node,
                      @Nullable
                      @Nullable ClusterNode evtNode,
                      String msg,
                      int type,
                      int part,
                      boolean near,
                      Object key,
                      IgniteUuid xid,
                      String txLbl,
                      Object lockId,
                      Object newVal,
                      boolean hasNewVal,
                      Object oldVal,
                      boolean hasOldVal,
                      UUID subjId,
                      String cloClsName,
                      String taskName)

Constructs cache event.

Parameters:
  `cacheName` - Cache name.
  `node` - Local node.
  `evtNode` - Event node ID.
  `msg` - Event message.
  `type` - Event type.
  `part` - Partition for the event (usually the partition the key belongs to).
  `near` - Flag indicating whether event happened on `near` or `partitioned` cache.
  `key` - Cache key.
  `xid` - Transaction ID.
  `txLbl` - Transaction label.
  `lockId` - Lock ID.
  `newVal` - New value.
  `hasNewVal` - Flag indicating whether new value is present in case if we don't have it in deserialized form.
  `oldVal` - Old value.
  `hasOldVal` - Flag indicating whether old value is present in case if we don't have it in deserialized form.
  `subjId` - Subject ID.
  `cloClsName` - Closure class name.
  `taskName` - Name of the task if cache event was caused by an operation initiated within task execution.

### Method Detail

#### cacheName

    public String cacheName()

Gets cache name.

Returns:
  Cache name.

#### partition

    public int partition()

Gets partition for the event which is the partition the key belongs to.

Returns:
  Partition for the event.

#### isNear

    public boolean isNear()

Gets flag indicating whether event happened on `near` or `partitioned` cache.

Returns:
  Flag indicating whether event happened on `near` or `partitioned` cache.

#### eventNode

    public ClusterNode eventNode()

Gets node which initiated cache operation or `null` if that node is not available.

Returns:
  Node which initiated cache operation or `null` if that node is not available.

#### key

    public <K> K key()

Gets cache entry associated with event.

Type Parameters:
  `K` - Cache entry type.
Returns:
  Cache entry associated with event.

#### xid

    public IgniteUuid xid()

ID of surrounding cache transaction or `null` if there is no surrounding transaction.

Returns:
  ID of surrounding cache transaction.

#### txLabel

    public String txLabel()

Label of surrounding cache transaction or `null` if there either is no surrounding transaction or label was not set.

Returns:
  Label of surrounding cache transaction.

#### lockId

    public Object lockId()

ID of the lock if held or `null` if no lock held.

Returns:
  ID of the lock if held.

#### newValue

    public Object newValue()

Gets new value for this event.

Returns:
  New value associated with event (`null` if event is `EventType.EVT_CACHE_OBJECT_REMOVED`.

#### oldValue

    public Object oldValue()

Gets old value associated with this event.

Returns:
  Old value associated with event.

#### hasOldValue

    public boolean hasOldValue()

Gets flag indicating whether cache entry has old value in case if we only have old value in serialized form in which case `oldValue()` will return `null`.

Returns:
  Flag indicating whether there is old value associated with this event.

#### hasNewValue

    public boolean hasNewValue()

Gets flag indicating whether cache entry has new value in case if we only have new value in serialized form in which case `newValue()` will return `null`.

Returns:
  Flag indicating whether there is new value associated with this event.

#### subjectId

    public UUID subjectId()

Gets security subject ID initiated this cache event, if security is enabled. This property is not available for `EventType.EVT_CACHE_NODES_LEFT`, `EventType.EVT_CACHE_ENTRY_EVICTED` and `EventType.EVT_CACHE_OBJECT_EXPIRED` cache events.

Returns:
  Subject ID if security is enabled, otherwise null.
See Also:
  `IgniteSecurity.enabled()`

#### closureClassName

    public String closureClassName()

Gets closure class name (applicable only for TRANSFORM operations).

Returns:
  Closure class name.

#### taskName

    public String taskName()

Gets task name if cache event was caused by an operation initiated within task execution.

Returns:
  Task name.

#### shortDisplay

    public String shortDisplay()

Gets a shortened version of `toString()` result. Suitable for humans to read.

Specified by:
  `shortDisplay` in interface `Event`
Overrides:
  `shortDisplay` in class `EventAdapter`
Returns:
  Shortened version of `toString()` result.

#### toString

    public String toString()

Overrides:
  `toString` in class `EventAdapter`

${current.year} Copyright © Apache Software Foundation

Follow @ApacheIgnite

Ignite Database and Caching Platform | : ver. 2.15.0
Release Date | : April 25 2023