Package 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 | 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
    Modifier and Type | Method | Description
    --- | --- | ---
    `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`