# Event propagation control

## Introduction

The goal is to statically control the publishing and subscription of event notifications. 

Event propagation is not always desirable in an execution graph. Certain nodes may decide to opt out of the execution path. There are two dimensions we want to control, the sending of event notifications from an EventHandler and the subscription of node to the updates of a parent node.

We can control dynamically the event broadcast using a dirty flag from the OnEvent method, but this falls short of the requirements we want to meet:

* Statically defined behaviour that cannot be toggled.
* An EventHandler can decide to halt broadcasts to all child nodes.
* A child node can filter all notification updates from a particular parent node.

### Publisher control

A node may have multiple event handler methods, and some should not initiate an execution path cycle. For example a config event does not initiate the event cycle but an application event will do. This is the event publisher controlling the broadcast.

### Subscriber control

Similarly a child node may refer to a cache node but updates to the cache node will be ignored. The cache will be accessed when another parent node broadcasts a change notification, whereas another client may want to process all cache updates. This is the client controlling its own subscription.

### Annotation support

Fluxtion provides two annotations that control the notification publication.

| Annotation                                                                                                                                                   | Behaviour                                                                     |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| [@NoEventReference](https://github.com/v12technology/fluxtion/blob/master/builder/src/main/java/com/fluxtion/api/annotations/NoEventReference.java)          | Removes this class as a subscriber to the marked nodes event subscriber list. |
| [@EventHandler (propagate= false)](https://github.com/v12technology/fluxtion/blob/master/api/src/main/java/com/fluxtion/runtime/lifecycle/EventHandler.java) | Propagate enables publication of events to child nodes.                       |

## Example

The example provides a combination of NoEventReference and EventHandler(propagate=false) examples. The nodes are annotated to support the following behaviour:

| Node                         | Propagation behaviour                                                                               |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `PropagateControlledNode`    | Ignore events from DataEventHandler, and receive all events published by PropagateControlledhandler |
| `PropagateControlledhandler` | will swallow ConfigEvents and broadcast MyEvent's.                                                  |

The code for the example is located [here](https://github.com/v12technology/fluxtion/tree/master/examples/documentation-examples/src/main/java/com/fluxtion/example/core/events/propagation).

### The node classes

```java
public class PropagateControlledhandler {
    @EventHandler
    public void broadcastEvent(MyEvent event){}
    
    @EventHandler(propagate = false)
    public void silentEvent(ConfigEvent event){}
}


public class PropagateControlledNode {
    private final PropagateControlledhandler handler;

    @NoEventReference
    private final DataEventHandler datahandler;

    public PropagateControlledNode(PropagateControlledhandler handler, DataEventHandler datahandler) {
        this.handler = handler;
        this.datahandler = datahandler;
    }
    
    @OnEvent
    public void update(){}

}

```

### Generated SEP

As expected the only event that propagates to the PropagateControlledNode is MyEvent channeled through PropagateControlledhandler.

```java
public class SampleProcessor implements EventHandler, BatchHandler, Lifecycle {

  //Node declarations
  private final DataEventHandler dataEventHandler_1 = new DataEventHandler();
  private final PropagateControlledhandler propagateControlledhandler_3 =
      new PropagateControlledhandler();
  private final PropagateControlledNode propagateControlledNode_5 =
      new PropagateControlledNode(propagateControlledhandler_3, dataEventHandler_1);
  //code omitted for clarity

  public void handleEvent(ConfigEvent typedEvent) {
    //Default, no filter methods
    propagateControlledhandler_3.silentEvent(typedEvent);
    //event stack unwind callbacks
    afterEvent();
  }

  public void handleEvent(DataEvent typedEvent) {
    //Default, no filter methods
    dataEventHandler_1.handleEvent(typedEvent);
    //event stack unwind callbacks
    afterEvent();
  }

  public void handleEvent(MyEvent typedEvent) {
    //Default, no filter methods
    propagateControlledhandler_3.broadcastEvent(typedEvent);
    propagateControlledNode_5.update();
    //event stack unwind callbacks
    afterEvent();
  }

}
```

### Generated png

The graphical representation of this execution graph as generated by Fluxtion ESC.

![Example SEP with propagation control](/files/-LU2mWZ1rU_XaLkMT_ui)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fluxtion.gitbook.io/docs/examples/reference/child-2/event-propagation-control.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.