Event Listening

Edit pageLast modified: 19 February 2025

Plugins can subscribe to the flow of events from the Workspace Model.

EntityChange Events

The order of EntityChange events is predefined:

  1. EntityChange.Removed

  2. EntityChange.Replaced

  3. EntityChange.Added

The Added and Removed events are straightforward and generated in case of added or removed entities.

The Replaced event is generated in case if any of the fields of the entity changes the value in the newer version of storage. This event is generated in two cases:

  • "primitive" field change (Int, String, data class, etc.)

  • changes of references to other entities

The change of references may happen indirectly by modifying the referred entity. For example, when removing a child entity, two events are generated: Removed for a child and Replaced for a parent. When adding a new child entity, again two events will be generated: Added for a child and Replaced for a parent.

Examples

Example 1

Assuming the following structure of entities: A → B → C. Where A is the root entity and B is its child, and C is the child of B.

  • Modify a primitive field of C: [Replaced(C)]

  • Remove C: [Replaced(B), Removed(C)]

  • Remove reference between B and C: [Replaced(B), Replaced(C)]

  • Remove B: [Replaced(A), Removed(B), Removed(C)] – C is cascade removed

Example 2

Assuming the following structure of entities: Initial: A → B C After: A C → B

Move child B from A to C: [Replaced(A), Replaced(B), Replaced(C)]

Subscription via Kotlin Flow

Using Kotlin Coroutines, it is possible to subscribe to the events via Kotlin Flows exposed via the WorkspaceModel.eventLog property.

Flows allow performing incremental computation: calculate information based on the initial storage and modify it according to the updates. This can be useful for incremental updates of Workspace Model-related caches.

If the subscription should be set up after a project is opened, use ProjectActivity. Keep in mind that it might miss the few first updates of the model, which is expected because the initial version of the storage will be provided.

Since this listener is asynchronous, there is no guarantee that indexes built on top of WorkspaceFileIndex or the project model will be updated.

Incremental Computation

To perform incremental computations, the last known version of the storage and the event of updates is required. This can be obtained by collecting indexed events. Assume we build some index and keep it updated:

workspaceModel.eventLog.collectIndexed { index, event ->
  if (index == 0) {
    buildIndex(event.storageAfter)
  } else {
    updateIndex(event)
  }
}