Event Operator and Processor

[ATorrise]

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:

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 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:

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

[codecov]

Codecov Report

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

Project coverage is 91.08%. Comparing base (7df9fce) to head (8cb0253).
Report is 2 commits behind head on next.

Files	Patch %	Lines
packages/imperative/src/events/src/EventUtils.ts	63.07%	24 Missing ⚠️
packages/imperative/src/config/src/ProfileInfo.ts	50.00%	3 Missing ⚠️
packages/imperative/src/events/src/Event.ts	91.66%	1 Missing ⚠️
...ckages/imperative/src/events/src/EventProcessor.ts	98.36%	1 Missing ⚠️
...tive/src/security/src/CredentialManagerOverride.ts	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #2136      +/-   ##
==========================================
- Coverage   91.22%   91.08%   -0.14%     
==========================================
  Files         629      632       +3     
  Lines       17964    18007      +43     
  Branches     3831     3802      -29     
==========================================
+ Hits        16387    16402      +15     
- Misses       1576     1604      +28     
  Partials        1        1              

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

[zFernand0]

I know I'm not allowed to approve this PR, but FWIW...
LGTM! 😋

[traeok]

Thanks for your work on this @ATorrise and @zFernand0! I left a few comments, some for my own edification. It looks like there are some functions across the new Event classes that would benefit from adding @throws. I also had a question regarding the subscribe... function implementations.

[gejohnston]

Trae had some comments worth considering.
However, I have nothing else to add, so I am approving.

[zFernand0]

I believe all comments should be addressed in a4e268a

Thanks for the reviews.

We should have a short demo ready for later this week 😋

[traeok]

LGTM - thanks @ATorrise @zFernand0 !

[t1m0thyj]

LGTM, just one comment about potentially redundant code

[zFernand0]

Here is something worth checking, besides the few integration tests that are failing here:

• https://github.com/zowe/zowe-cli/actions/runs/9809870085/attempts/1

The above is a workflow that shows a few tests where the .events directory may fail to be created. Something to keep in mind in case other tests fail in a similar fashion. (Thanks @gejohnston for the pointer)

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
85.9% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarCloud

[github-actions]

Release succeeded for the next branch. 🎉

The following packages have been published:

• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]
• npm: @zowe/[email protected]

_{Powered by Octorelease 🚀}