Event Operator and Processor

ATorrise commented 1 month ago

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

Imagine you have a Notepad application that wants to subscribe to events from a Calculator application to display the numbers typed in the Calculator:

The Notepad application requests an EventProcessor instance with watch permissions for the Calculator from the EventOperator.
The Notepad application subscribes to the Calculator's "number pressed" event with a callback to display the number that was pressed.

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 callback/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

Singleton Management
- EventOperator manages singleton instances of EventProcessor for different applications. Retrieves existing instances or creates new ones as needed.
Subscription Management
- Each EventProcessor manages its own subscriptions, handling the addition, emission, and removal of events. It uses a map where event names are keys, and values are Event objects that hold detailed event information and subscriptions.
Event Emission
- Emitting an event updates its timestamp and the eventTimes map to meet 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/Zowe/$userEventName`	`$ZOWE_CLI_HOME/.events/Zowe/$sharedEventName`	`~/.zowe/.events/$appName/$customSharedEventName`	`$ZOWE_CLI_HOME/.events/$appName/$customSharedEventName`

How to Test

Operate the sample VSCE without error:

Use the eeM-pre branch from zowe-cli-sample-scripts to operate a VSCE mock we have been testing with.
Navigate to your ZE Data Sets, right-click on an item in the list, and use the context menu to subscribe to events, emit events, and unsubscribe from events.

Review Checklist I certify that I have:

[x] tested my changes
[x] added/updated automated tests
[x] updated the changelog
[x] followed the contribution guidelines

codecov[bot] commented 1 month ago

Codecov Report

Attention: Patch coverage is 86.66667% with 30 lines in your changes missing coverage. Please review.

Project coverage is 91.05%. Comparing base (abadee5) to head (7403112). Report is 2 commits behind head on next.

Files	Patch %	Lines
packages/imperative/src/events/src/EventUtils.ts	62.50%	24 Missing :warning:
packages/imperative/src/config/src/ProfileInfo.ts	50.00%	3 Missing :warning:
packages/imperative/src/events/src/Event.ts	91.66%	1 Missing :warning:
...ckages/imperative/src/events/src/EventProcessor.ts	98.41%	1 Missing :warning:
...tive/src/security/src/CredentialManagerOverride.ts	75.00%	1 Missing :warning:

Additional details and impacted files

```diff @@ Coverage Diff @@ ## next #2136 +/- ## ========================================== - Coverage 91.18% 91.05% -0.13% ========================================== Files 628 631 +3 Lines 17859 17902 +43 Branches 3799 3766 -33 ========================================== + Hits 16284 16300 +16 - Misses 1574 1601 +27 Partials 1 1 ```

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

t1m0thyj commented 3 weeks ago

Had to add an appendFileSync mock to Zowe Explorer in order to test code that calls the event emitter. Hopefully after this PR is merged that won't be necessary anymore 😋 See https://github.com/zowe/zowe-explorer-vscode/pull/2932/commits/1efd4f71a0cfa1e4acb2db38211bd27532bb630c