Event Operator and Processor

[ATorrise]

Warning

Wait for changes, don't review

Overview

The EventOperator class is a singleton controller for managing EventProcessor instances. It organizes event management for applications by mapping each application's name to an event processor, which manages and fires callbacks provided by the subscriber to a given application-specific event.

Example Use Case

To better understand this organization, imagine you have a Notepad application that wants to subscribe to events from a Calculator application to display the numbers typed in the Calculator:

1. The Notepad application requests an EventProcessor instance with watch permissions for the Calculator from the EventOperator.
2. The Notepad application subscribes to the Calculator's "number pressed" event with a callback to display the number that was pressed.
3. Whenever a number is pressed in the Calculator, the Notepad application receives the event and can display the number.

// Notepad application subscribing to Calculator's events
const calcProcessor = EventOperator.getWatcher('calculator');
calcProcessor.subscribeUser('numberPressed', (number) => {
  notepad.display(`Number ${number} pressed in Calculator`);
  // fake code to show notepad's event handling
});

Design Pattern

Instances of EventProcessor are stored within a static map inside EventOperator, keyed by application names. This prevents cross-application event collisions, maintains a clean separation of events, and allows multiple applications to subscribe to the same application-specific events efficiently.

Functionality

• EventOperator manages singleton instances of EventProcessor for different applications.
  • When you pass in an application name to create an EventProcessor, it retrieves the existing instance for that application if it already exists, or creates a new one if it doesn't. This ensures that only one EventProcessor instance exists for a given application.
• Each EventProcessor manages its own subscriptions, handling the addition, emission, and removal of events. It uses a map where event names are the keys, and the values are Event objects that hold detailed event information and its list of subscriptions.
• Emitting an event updates its timestamp and the 'eventTimes' map to meet the specific timing requirements for FsWatcher.

Code Examples

EventUtils.getListOfApps()
// Output: [fakeApp, fakeApp_vsce, Zowe]

const watcherInstance = EventOperator.getWatcher('fakeApp'); 
processor.subscribeShared('sharedEvent', callback); 
processor.unsubscribe('sharedEvent');`

const bothInstance= EventOperator.getProcessor('fakeApp_vsce'); 
bothInstance.subscribeUser('userEvent', [callback1, callback2]);
bothInstance.emitEvent('userEvent'); 
bothInstance.emitEvent('otherEvent'); 
bothInstance.unsubscribe('userEvent'); 

Event Types Explained

Within our system, events are categorized into four main types:

	Zowe User Events	Zowe Shared Events	User Events	Shared Events
Event Origin	Zowe CLI	Zowe CLI	Extender Applications	Extender Applications
Use case	Derived from the Zowe CLI only, these events are triggered by actions directly related to user interactions or specific user activities.	Derived from the Zowe CLI only, these events are relevant to multiple users of a shared system and need to be accessible by various components or services.	These events are specific to the extender’s application and are customizable. To be used for user-specific changes and settings.	These events are specific to the extender’s application. To be used when an event is relevant to multiple users of a shared system or the event needs to be watched by various components or services.
Event file path	~/.zowe/.events/$userEventName	$ZOWE_CLI_HOME/.events/$sharedEventName	~/.zowe/.events/$appName/$customSharedEventName	$ZOWE_CLI_HOME/.events/$appName/$customSharedEventName

How to Test

• Operate the sample VSCE without error. Use the eeM-pre of our VSCE mock
  • The VSCE builds off of ZE. Navigate to your ZE Data Sets, right click on an item in the list, use that context menu to subscribe to events, emit events, and unsubscribe from events

Remaining Work

• Tests!!!

Review Checklist
I certify that I have:

• tested my changes
• added/updated automated tests
• updated the changelog
• followed the contribution guidelines

[codecov]

Codecov Report

Attention: Patch coverage is 35.58559% with 143 lines in your changes are missing coverage. Please review.

Project coverage is 83.28%. Comparing base (d68e05d) to head (1eaad24).
Report is 64 commits behind head on next.

Files	Patch %	Lines
packages/imperative/src/events/src/EventUtils.ts	23.43%	49 Missing ⚠️
...ckages/imperative/src/events/src/EventProcessor.ts	31.66%	41 Missing ⚠️
...ackages/imperative/src/events/src/EventOperator.ts	21.05%	30 Missing ⚠️
packages/imperative/src/events/src/Event.ts	8.33%	11 Missing ⚠️
packages/imperative/src/config/src/ConfigUtils.ts	63.15%	7 Missing ⚠️
packages/imperative/src/config/src/ProfileInfo.ts	33.33%	2 Missing ⚠️
...tive/src/security/src/CredentialManagerOverride.ts	50.00%	2 Missing ⚠️
...ages/imperative/src/config/src/api/ConfigSecure.ts	66.66%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #2136      +/-   ##
==========================================
- Coverage   91.20%   83.28%   -7.93%     
==========================================
  Files         628      631       +3     
  Lines       17877    17927      +50     
  Branches     3750     3685      -65     
==========================================
- Hits        16305    14930    -1375     
- Misses       1571     2996    +1425     
  Partials        1        1              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[gejohnston]

Consumers, who were not in your design meetings, will not understand why an EventOperator, EventProcessor and EventEmitter exist, nor how they should use them. I suggest that we provide more explanation in block comments on the classes themselves and on some of the more prominent functions to describe how we intend these items to be used. I called out a couple specific examples in the code to give an idea of what I am thinking.

I will continue reviewing other details in this pull request, but I wanted to post this early round of comments for your consideration.

[gejohnston]

This is where a caller will start using our set of event technology. That makes this the best place to provide an overview of what the technology is about (including some things implemented in other classes).

Use this block comment to define an EventOperator, and the watchers, emitters, EmitterAndWatchers that are managed by an EventOperator. Provide more context of how an app uses the EventOperator to acquire and manage different watchers, and emitters. Point out when an app should get a processor for emitting versus watching. Clarify the kinds of things the app should do with a given EventProcessor. Explain how the getXXX functions returns different interfaces which restrict which operations you can perform with that particular EventProcessor.

Describe how a processor is tied to an app name and why. Explain that pre-existing, well-defined zowe events exist and can be watched. Point to where a caller can find such names. Explain that custom events can be defined by an arbitrary app. Explain that the valid app names are in our list of extenders (which are the formal plugin names or ZE extender names).

[gejohnston]

Explain why a user would get one of these and what they would do with it.

[gejohnston]

Elaborate on what it means to the caller to emit an event. Explain why a caller might want to subscribe to an event. Explain that subscribing involves supplying a callback function. Define what a shared event is versus a user event.