Implemented external API

This commit provides an external API that can be used by other
extensions to communicate with the base trace extension. The
current API provides a way to retrieve the active experiment as well as
fire events and register callbacks. This is the initial API and will be
further expanded in future commits.

Fixes #140

Signed-off-by: Neel Gondalia <[email protected]>

Author: ngondalia

README.md

@@ -215,3 +215,78 @@ yarn playwright test --retries <retries>
 [vscode-messages]: https://code.visualstudio.com/api/extension-guides/webview#passing-messages-from-an-extension-to-a-webview
 [vscode-webview]: https://github.com/rebornix/vscode-webview-react
 [vscode-webview-react]: https://github.com/rebornix/vscode-webview-react
+
+## Using the External API
+
+VSCode Trace Extension provides an external API that adopter extensions can rely on for communication. Currently the API is limited to the following:
+
+```javascript
+getActiveExperiment(): Experiment | undefined,
+getEvents(): RegisteredEventEmitter<unknown>[],
+fireEvent(registeredEvent: RegisteredEventEmitter<unknown>, data: unknown): void,
+createSignalCallbackInterface(signal: string, callback: (data: unknown) => void): SignalCallbackInterface;
+onEventRegistered(listener: (event: RegisteredEventEmitter<unknown>) => void): void,
+onEventDisposed(listener: (event: RegisteredEventEmitter<unknown>) => void): void
+```
+
+### Using the API from Adopter Extensions
+```javascript
+//The following retrieves the API object from the vscode-trace-extension
+const ext = vscode.extensions.getExtension("tracecompass-community.vscode-trace-extension");
+const importedApi = ext.exports;
+```
+Once you have the API object, you can proceed to make API calls. For example, if you wish to retrieve the active experiment in the Trace Viewer, the following API call can be used:
+```javascript
+const experiment = importedApi.getActiveExperiment();
+```
+
+The API also provides a signaling mechanism so that the adopter extensions can fire/subscribe to events.
+```javascript
+/**
+ * Returns the registered events that can be fired by the adopter extensions.
+ */
+const events = importedApi.getEvents();
+
+for (const event of events) {
+    const data = importedApi.createSignalCallbackInterface('experimentSelected', () => {
+        console.log("experiment selected signal fired");
+    });
+    importedApi.fireEvent(event, data);
+}
+
+/**
+ * Adopter extensions can also attach listeners for when new events are registered/disposed
+ */
+importedApi.onEventRegistered((event) => {
+    //handle new event registered
+});
+
+onNewEventRegistered.onEventDisposed(event => {
+    //handle disposed events
+})
+```
+
+Currently, the only registered events in the base extension is "traceExplorer.openedTracesView.register_callback". Upon firing this event, you can register a callback for a given signal to the OpenedTracesView. Note that this event is registered/disposed with the webview, so it is recommended to add listeners for 'onEventRegistered' and 'onEventDisposed'.
+
+### RegisteredEventEmitter Class
+
+The 'RegisteredEventEmitter' class has the following properties:
+```javascript
+//Unique Identifier
+id: string;
+//Event Emitter
+eventEmitter: vscode.EventEmitter<T>;
+//Event Handler for the event
+onEventHandler: (data: unknown) => void;
+//Type of data the event handler expects
+type: DataType;
+```
+When firing events from the adopter extensions, it is recommended to inspect the 'type' property and use the API to create objects based on the type.
+```javascript
+if (event.type === 'SignalCallbackInterface') {
+        const data = importedApi.createSignalCallbackInterface('experimentSelected', () => {
+        console.log("experiment selected signal fired");
+    });
+    importedApi.fireEvent(event, data);
+}
+```

vscode-trace-extension/src/extension.ts

@@ -8,10 +8,13 @@ import { fileHandler, openOverviewHandler, resetZoomHandler, undoRedoHandler, zo
 import { TraceServerConnectionStatusService } from './utils/trace-server-status';
 import { updateTspClient } from './utils/tspClient';
 import { TraceExtensionLogger } from './utils/trace-extension-logger';
+import { ExternalAPI, traceExtensionAPI} from './external-api/external-api';
+import { TraceExtensionEventManager } from './utils/trace-extension-event-manager';
 
 export let traceLogger: TraceExtensionLogger;
+export const traceExtensionEventManager: TraceExtensionEventManager = new TraceExtensionEventManager();
 
-export function activate(context: vscode.ExtensionContext): void {
+export function activate(context: vscode.ExtensionContext): ExternalAPI {
     traceLogger = new TraceExtensionLogger('Trace Extension');
 
     const serverStatusBarItemPriority = 1;
@@ -93,6 +96,7 @@ export function activate(context: vscode.ExtensionContext): void {
     context.subscriptions.push(vscode.commands.registerCommand('serverStatus.stopped', () => {
         serverStatusService.render(false);
     }));
+    return traceExtensionAPI;
 }
 
 export function deactivate(): void {

vscode-trace-extension/src/external-api/external-api.ts

@@ -0,0 +1,80 @@
+/***************************************************************************************
+ * Copyright (c) 2023 BlackBerry Limited and others.
+ *
+ * Licensed under the MIT license. See LICENSE file in the project root for details.
+ ***************************************************************************************/
+import { Experiment } from 'tsp-typescript-client/lib/models/experiment';
+import { TraceViewerPanel } from '../trace-viewer-panel/trace-viewer-webview-panel';
+import { traceExtensionEventManager } from '../extension';
+import { RegisteredEventEmitter, SignalCallbackInterface } from '../utils/trace-extension-event-manager';
+
+export interface ExternalAPI {
+    getActiveExperiment(): Experiment | undefined,
+    getEvents(): RegisteredEventEmitter<unknown>[],
+    fireEvent(registeredEvent: RegisteredEventEmitter<unknown>, data: unknown): void,
+    createSignalCallbackInterface(signal: string, callback: (data: unknown) => void): SignalCallbackInterface;
+    onEventRegistered(listener: (event: RegisteredEventEmitter<unknown>) => void): void,
+    onEventDisposed(listener: (event: RegisteredEventEmitter<unknown>) => void): void
+}
+
+export const traceExtensionAPI: ExternalAPI = {
+    /**
+     * Retrieves the currently active experiement
+     *
+     * @returns Experiment if one is currently active, otherwise undefined
+     */
+    getActiveExperiment(): Experiment | undefined {
+        return TraceViewerPanel.getCurrentExperiment();
+    },
+
+    /**
+     * Retrieves the list of event emitters registered with the Event Manager
+     *
+     * @returns list of event emitter IDs
+     */
+    getEvents(): RegisteredEventEmitter<unknown>[] {
+        return traceExtensionEventManager.getRegisteredEvents();
+    },
+
+    /**
+     * Fires the event emitter with the provided ID
+     *
+     * @param eventId ID of the event emitter to fire
+     * @param data event object
+     */
+    fireEvent(registeredEvent: RegisteredEventEmitter<unknown>, data: unknown): void {
+        traceExtensionEventManager.fireEvent(registeredEvent, data);
+    },
+
+    /**
+     * Creates a SignalCallbackInterface which is passed as a data for certain Event Emitters
+     *
+     * @param _signal signal to attach the callback to
+     * @param _callback function to call when the signal is fired
+     * @returns SignalCallbackInterface object
+     */
+    createSignalCallbackInterface(_signal: string, _callback: (data: unknown) => void): SignalCallbackInterface {
+        return {
+            _signal: _signal,
+            _callback: _callback
+        };
+    },
+
+    /**
+     * Attaches listener for when an event is registered
+     *
+     * @param listener event listener
+     */
+    onEventRegistered(listener: (event: RegisteredEventEmitter<unknown>) => unknown): void {
+        traceExtensionEventManager.onNewEventRegistered(listener);
+    },
+
+    /**
+     * Attaches listener for when events are disposed
+     *
+     * @param listener event listener
+     */
+    onEventDisposed(listener: (event: RegisteredEventEmitter<unknown>) => unknown): void {
+        traceExtensionEventManager.onEventDisposed(listener);
+    },
+};

vscode-trace-extension/src/trace-explorer/opened-traces/trace-explorer-opened-traces-webview-provider.ts

@@ -8,6 +8,8 @@ import { TraceViewerPanel } from '../../trace-viewer-panel/trace-viewer-webview-
 import { TraceServerConnectionStatusService } from '../../utils/trace-server-status';
 import { getTraceServerUrl, getTspClientUrl } from '../../utils/tspClient';
 import { VSCODE_MESSAGES } from 'vscode-trace-common/lib/messages/vscode-message-manager';
+import { traceExtensionEventManager } from 'vscode-trace-extension/src/extension';
+import { DataType, SignalCallbackInterface } from '../../utils/trace-extension-event-manager';
 
 const JSONBig = JSONBigConfig({
     useNativeBigInt: true,
@@ -16,12 +18,13 @@ const JSONBig = JSONBigConfig({
 export class TraceExplorerOpenedTracesViewProvider implements vscode.WebviewViewProvider {
 
 	public static readonly viewType = 'traceExplorer.openedTracesView';
+	public static readonly eventEmitter_id_callback = this.viewType + '.register_callback';
 
 	private _view?: vscode.WebviewView;
 	private _disposables: vscode.Disposable[] = [];
 	private _selectedExperiment: Experiment | undefined;
 
-   	constructor(
+	constructor(
 		private readonly _extensionUri: vscode.Uri,
 		private readonly _statusService: TraceServerConnectionStatusService,
 	) {}
@@ -52,6 +55,16 @@ export class TraceExplorerOpenedTracesViewProvider implements vscode.WebviewView
 	    }
 	}
 
+	protected registerCallbackForSignal(data: SignalCallbackInterface): void {
+		this._view?.webview.onDidReceiveMessage(message => {
+		    switch (message.command) {
+		    case data._signal: {
+		        data._callback(message);
+		    }
+		    }
+		});
+	}
+
 	protected doHandleExperimentSelectedSignal(experiment: Experiment | undefined): void {
 	    if (this._view) {
 	        this._selectedExperiment = experiment;
@@ -65,6 +78,11 @@ export class TraceExplorerOpenedTracesViewProvider implements vscode.WebviewView
 	): void {
 	    this._view = webviewView;
 
+	    // Registers an event with the traceExtensionEventManager to register callbacks for signals received in this webview
+	    const registerCallbackEvent = traceExtensionEventManager.registerEventEmitter(webviewView.viewType + '.register-callback',
+	        (data: unknown) => {this.registerCallbackForSignal(data as SignalCallbackInterface);},
+	        DataType.SignalCallback);
+
 	    webviewView.webview.options = {
 	        // Allow scripts in the webview
 	        enableScripts: true,
@@ -132,6 +150,7 @@ export class TraceExplorerOpenedTracesViewProvider implements vscode.WebviewView
 	        signalManager().off(Signals.TRACEVIEWERTAB_ACTIVATED, this._onOpenedTracesWidgetActivated);
 	        signalManager().off(Signals.OPENED_TRACES_UPDATED, this._onOpenedTracesChanged);
 	        signalManager().off(Signals.EXPERIMENT_SELECTED, this._onExperimentSelected);
+	        traceExtensionEventManager.disposeEvent(registerCallbackEvent);
 	    }, undefined, this._disposables);
 	}
 

vscode-trace-extension/src/trace-viewer-panel/trace-viewer-webview-panel.ts

@@ -86,6 +86,10 @@ export class TraceViewerPanel {
 		TraceViewerPanel.currentPanel?.updateZoom(hasZoomedIn);
 	}
 
+	public static getCurrentExperiment(): Experiment | undefined {
+	    return TraceViewerPanel.currentPanel?._experiment;
+	}
+
 	private static async saveTraceCsv(csvData: string, defaultFileName: string) {
 	    const saveDialogOptions = {
 	        defaultUri: vscode.workspace.workspaceFolders