@theia/plugin 1.32.0-next.25 → 1.32.0-next.28

package/README.md

@@ -490,19 +490,22 @@ In case if a few providers are registered the chain will be executed until one o
 To contribute a hover it is only needed to provide a function that can be called with a `TextDocument` and a `Position` returning hover info. Registration is done using a document selector which either a language id ('typescript', 'javascript' etc.) or a more complex filter like `{scheme: 'file', language: 'typescript'}`.
 
 For example,
+
 ```typescript
 theia.languages.registerHoverProvider('typescript', {
-    provideHover(doc: theia.TextDocument, position: theia.Position) {
+    provideHover(doc: theia.TextDocument, position: theia.Position, token: theia.CancellationToken) {
         return new theia.Hover('Hover for all **typescript** files.');
     }
 });
 ```
+
 will show the hover message for all `typescript` files.
 
 The code below puts word under cursor into hover message:
+
 ```typescript
 theia.languages.registerHoverProvider({scheme: 'file'}, {
-    provideHover(doc: theia.TextDocument, position: theia.Position) {
+    provideHover(doc: theia.TextDocument, position: theia.Position, token: theia.CancellationToken) {
         const range = doc.getWordRangeAtPosition(position);
         const text = doc.getText(range);
         return new theia.Hover(text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.32.0-next.25+e48b1fd88",
+  "version": "1.32.0-next.28+432ee41a1",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -32,5 +32,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "e48b1fd8898cb7da368100fd5ef64c3476a21577"
+  "gitHead": "432ee41a1e67d62704596fc7f8f90c8bb7a5b75f"
 }

package/src/theia-extra.d.ts

@@ -14,6 +14,8 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
 // *****************************************************************************
 
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
 /**
  * This is the place for extra APIs Theia supports compared to VS Code.
  */
@@ -33,4 +35,263 @@ export module '@theia/plugin' {
         reveal(area?: WebviewPanelTargetArea, viewColumn?: ViewColumn, preserveFocus?: boolean): void;
     }
 
+    export type PluginType = 'frontend' | 'backend';
+
+    /**
+     * Namespace for dealing with installed plug-ins. Plug-ins are represented
+     * by an [plug-in](#Plugin)-interface which enables reflection on them.
+     *
+     * Plug-in writers can provide APIs to other plug-ins by returning their API public
+     * surface from the `start`-call.
+     *
+     * ```javascript
+     * export function start() {
+     *     let api = {
+     *         sum(a, b) {
+     *             return a + b;
+     *         },
+     *         mul(a, b) {
+     *             return a * b;
+     *         }
+     *     };
+     *     // 'export' public api-surface
+     *     return api;
+     * }
+     * ```
+     * ```javascript
+     * let mathExt = plugins.getPlugin('genius.math');
+     * let importedApi = mathExt.exports;
+     *
+     * console.log(importedApi.mul(42, 1));
+     * ```
+     */
+    export namespace plugins {
+        /**
+         * Get an plug-in by its full identifier in the form of: `publisher.name`.
+         *
+         * @param pluginId An plug-in identifier.
+         * @return An plug-in or `undefined`.
+         */
+        export function getPlugin(pluginId: string): Plugin<any> | undefined;
+
+        /**
+         * Get an plug-in its full identifier in the form of: `publisher.name`.
+         *
+         * @param pluginId An plug-in identifier.
+         * @return An plug-in or `undefined`.
+         */
+        export function getPlugin<T>(pluginId: string): Plugin<T> | undefined;
+
+        /**
+         * All plug-ins currently known to the system.
+         */
+        export let all: Plugin<any>[];
+
+        /**
+         * An event which fires when `plugins.all` changes. This can happen when extensions are
+         * installed, uninstalled, enabled or disabled.
+         */
+        export let onDidChange: Event<void>;
+    }
+
+    /**
+     * Represents an plugin.
+     *
+     * To get an instance of an `Plugin` use {@link plugins.getPlugin getPlugin}.
+     */
+    export interface Plugin<T> {
+
+        /**
+         * The canonical plug-in identifier in the form of: `publisher.name`.
+         */
+        readonly id: string;
+
+        /**
+         * The absolute file path of the directory containing this plug-in.
+         */
+        readonly pluginPath: string;
+
+        /**
+         * The uri of the directory containing this plug-in.
+         */
+        readonly pluginUri: Uri;
+
+        /**
+         * `true` if the plug-in has been activated.
+         */
+        readonly isActive: boolean;
+
+        /**
+         * The parsed contents of the plug-in's package.json.
+         */
+        readonly packageJSON: any;
+
+        /**
+         *
+         */
+        readonly pluginType: PluginType;
+
+        /**
+         * The public API exported by this plug-in. It is an invalid action
+         * to access this field before this plug-in has been activated.
+         */
+        readonly exports: T;
+
+        /**
+         * Activates this plug-in and returns its public API.
+         *
+         * @return A promise that will resolve when this plug-in has been activated.
+         */
+        activate(): Thenable<T>;
+    }
+
+    /**
+     * A plug-in context is a collection of utilities private to a
+     * plug-in.
+     *
+     * An instance of a `PluginContext` is provided as the first
+     * parameter to the `start` of a plug-in.
+     */
+    export interface PluginContext {
+
+        /**
+         * An array to which disposables can be added. When this
+         * extension is deactivated the disposables will be disposed.
+         */
+        subscriptions: { dispose(): any }[];
+
+        /**
+         * A memento object that stores state in the context
+         * of the currently opened {@link workspace.workspaceFolders workspace}.
+         */
+        workspaceState: Memento;
+
+        /**
+         * A memento object that stores state independent
+         * of the current opened {@link workspace.workspaceFolders workspace}.
+         */
+        globalState: Memento & {
+            /**
+             * Set the keys whose values should be synchronized across devices when synchronizing user-data
+             * like configuration, extensions, and mementos.
+             *
+             * Note that this function defines the whole set of keys whose values are synchronized:
+             *  - calling it with an empty array stops synchronization for this memento
+             *  - calling it with a non-empty array replaces all keys whose values are synchronized
+             *
+             * For any given set of keys this function needs to be called only once but there is no harm in
+             * repeatedly calling it.
+             *
+             * @param keys The set of keys whose values are synced.
+             */
+            setKeysForSync(keys: readonly string[]): void;
+        };
+
+        /**
+         * A storage utility for secrets.
+         */
+        readonly secrets: SecretStorage;
+
+        /**
+         * The absolute file path of the directory containing the extension.
+         */
+        extensionPath: string;
+
+        /**
+         * The uri of the directory containing the extension.
+         */
+        readonly extensionUri: Uri;
+
+        /**
+         * Gets the extension's environment variable collection for this workspace, enabling changes
+         * to be applied to terminal environment variables.
+         */
+        readonly environmentVariableCollection: EnvironmentVariableCollection;
+
+        /**
+         * Get the absolute path of a resource contained in the extension.
+         *
+         * @param relativePath A relative path to a resource contained in the extension.
+         * @return The absolute path of the resource.
+         */
+        asAbsolutePath(relativePath: string): string;
+
+        /**
+         * An absolute file path of a workspace specific directory in which the extension
+         * can store private state. The directory might not exist on disk and creation is
+         * up to the extension. However, the parent directory is guaranteed to be existent.
+         *
+         * Use [`workspaceState`](#PluginContext.workspaceState) or
+         * [`globalState`](#PluginContext.globalState) to store key value data.
+         *
+         * @deprecated Use {@link PluginContext.storageUri storageUri} instead.
+         */
+        storagePath: string | undefined;
+
+        /**
+         * The uri of a workspace specific directory in which the extension
+         * can store private state. The directory might not exist and creation is
+         * up to the extension. However, the parent directory is guaranteed to be existent.
+         * The value is `undefined` when no workspace nor folder has been opened.
+         *
+         * Use [`workspaceState`](#PluginContext.workspaceState) or
+         * [`globalState`](#PluginContext.globalState) to store key value data.
+         *
+         * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from
+         *  an uri.
+         */
+        readonly storageUri: Uri | undefined;
+
+        /**
+         * An absolute file path in which the extension can store global state.
+         * The directory might not exist on disk and creation is
+         * up to the extension. However, the parent directory is guaranteed to be existent.
+         *
+         * Use [`globalState`](#PluginContext.globalState) to store key value data.
+         *
+         * @deprecated Use {@link PluginContext.globalStorageUri globalStorageUri} instead.
+         */
+        readonly globalStoragePath: string;
+
+        /**
+         * The uri of a directory in which the extension can store global state.
+         * The directory might not exist on disk and creation is
+         * up to the extension. However, the parent directory is guaranteed to be existent.
+         *
+         * Use [`globalState`](#PluginContext.globalState) to store key value data.
+         *
+         * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from
+         *  an uri.
+         */
+        readonly globalStorageUri: Uri;
+
+        /**
+         * An absolute file path of a directory in which the extension can create log files.
+         * The directory might not exist on disk and creation is up to the extension. However,
+         * the parent directory is guaranteed to be existent.
+         */
+        readonly logPath: string;
+
+        /**
+         * The mode the extension is running in. This is specific to the current
+         * extension. One extension may be in `ExtensionMode.Development` while
+         * other extensions in the host run in `ExtensionMode.Release`.
+         */
+        readonly extensionMode: ExtensionMode;
+
+        /**
+         * The current extension instance.
+         */
+        readonly extension: Plugin<any> | undefined;
+
+        /**
+         * The uri of a directory in which the extension can create log files. The directory might
+         * not exist on disk and creation is up to the extension. However, the parent directory is
+         * guaranteed to be existent.
+         * see - workspace.fs for how to read and write files and folders from an uri.
+         */
+        readonly logUri: Uri;
+    }
+
 }
+

package/src/theia.d.ts

@@ -63,116 +63,6 @@ export module '@theia/plugin' {
 
     }
 
-    export type PluginType = 'frontend' | 'backend';
-
-    /**
-     * Represents an plugin.
-     *
-     * To get an instance of an `Plugin` use {@link plugins.getPlugin getPlugin}.
-     */
-    export interface Plugin<T> {
-
-        /**
-         * The canonical plug-in identifier in the form of: `publisher.name`.
-         */
-        readonly id: string;
-
-        /**
-         * The absolute file path of the directory containing this plug-in.
-         */
-        readonly pluginPath: string;
-
-        /**
-         * The uri of the directory containing this plug-in.
-         */
-        readonly pluginUri: Uri;
-
-        /**
-         * `true` if the plug-in has been activated.
-         */
-        readonly isActive: boolean;
-
-        /**
-         * The parsed contents of the plug-in's package.json.
-         */
-        readonly packageJSON: any;
-
-        /**
-         *
-         */
-        readonly pluginType: PluginType;
-
-        /**
-         * The public API exported by this plug-in. It is an invalid action
-         * to access this field before this plug-in has been activated.
-         */
-        readonly exports: T;
-
-        /**
-         * Activates this plug-in and returns its public API.
-         *
-         * @return A promise that will resolve when this plug-in has been activated.
-         */
-        activate(): Thenable<T>;
-    }
-
-    /**
-     * Namespace for dealing with installed plug-ins. Plug-ins are represented
-     * by an [plug-in](#Plugin)-interface which enables reflection on them.
-     *
-     * Plug-in writers can provide APIs to other plug-ins by returning their API public
-     * surface from the `start`-call.
-     *
-     * ```javascript
-     * export function start() {
-     *     let api = {
-     *         sum(a, b) {
-     *             return a + b;
-     *         },
-     *         mul(a, b) {
-     *             return a * b;
-     *         }
-     *     };
-     *     // 'export' public api-surface
-     *     return api;
-     * }
-     * ```
-     * ```javascript
-     * let mathExt = plugins.getPlugin('genius.math');
-     * let importedApi = mathExt.exports;
-     *
-     * console.log(importedApi.mul(42, 1));
-     * ```
-     */
-    export namespace plugins {
-        /**
-         * Get an plug-in by its full identifier in the form of: `publisher.name`.
-         *
-         * @param pluginId An plug-in identifier.
-         * @return An plug-in or `undefined`.
-         */
-        export function getPlugin(pluginId: string): Plugin<any> | undefined;
-
-        /**
-         * Get an plug-in its full identifier in the form of: `publisher.name`.
-         *
-         * @param pluginId An plug-in identifier.
-         * @return An plug-in or `undefined`.
-         */
-        export function getPlugin<T>(pluginId: string): Plugin<T> | undefined;
-
-        /**
-         * All plug-ins currently known to the system.
-         */
-        export let all: Plugin<any>[];
-
-        /**
-         * An event which fires when `plugins.all` changes. This can happen when extensions are
-         * installed, uninstalled, enabled or disabled.
-         */
-        export let onDidChange: Event<void>;
-    }
-
     /**
      * A command is a unique identifier of a function
      * which can be executed by a user via a keyboard shortcut,
@@ -2530,7 +2420,7 @@ export module '@theia/plugin' {
      * Registration can be split in two step: first register command without handler,
      * second register handler by command id.
      *
-     * Any contributed command are available to any plugin, command can be invoked
+     * Any contributed command are available to any extension, command can be invoked
      * by {@link commands.executeCommand executeCommand} function.
      *
      * Simple example that register command:
@@ -3514,31 +3404,130 @@ export module '@theia/plugin' {
     }
 
     /**
-     * A plug-in context is a collection of utilities private to a
-     * plug-in.
+     * In a remote window the extension kind describes if an extension
+     * runs where the UI (window) runs or if an extension runs remotely.
+     */
+    export enum ExtensionKind {
+
+        /**
+         * Extension runs where the UI runs.
+         */
+        UI = 1,
+
+        /**
+         * Extension runs where the remote extension host runs.
+         */
+        Workspace = 2
+    }
+
+    /**
+     * Represents an extension.
+     *
+     * To get an instance of an `Extension` use {@link extensions.getExtension getExtension}.
+     */
+    export interface Extension<T> {
+
+        /**
+         * The canonical extension identifier in the form of: `publisher.name`.
+         */
+        readonly id: string;
+
+        /**
+         * The uri of the directory containing the extension.
+         */
+        readonly extensionUri: Uri;
+
+        /**
+         * The absolute file path of the directory containing this extension. Shorthand
+         * notation for {@link Extension.extensionUri Extension.extensionUri.fsPath} (independent of the uri scheme).
+         */
+        readonly extensionPath: string;
+
+        /**
+         * `true` if the extension has been activated.
+         */
+        readonly isActive: boolean;
+
+        /**
+         * The parsed contents of the extension's package.json.
+         */
+        readonly packageJSON: any;
+
+        /**
+         * The extension kind describes if an extension runs where the UI runs
+         * or if an extension runs where the remote extension host runs. The extension kind
+         * is defined in the `package.json`-file of extensions but can also be refined
+         * via the `remote.extensionKind`-setting. When no remote extension host exists,
+         * the value is {@linkcode ExtensionKind.UI}.
+         */
+        extensionKind: ExtensionKind;
+
+        /**
+         * The public API exported by this extension (return value of `activate`).
+         * It is an invalid action to access this field before this extension has been activated.
+         */
+        readonly exports: T;
+
+        /**
+         * Activates this extension and returns its public API.
+         *
+         * @return A promise that will resolve when this extension has been activated.
+         */
+        activate(): Thenable<T>;
+    }
+
+    /**
+     * The ExtensionMode is provided on the `ExtensionContext` and indicates the
+     * mode the specific extension is running in.
+     */
+    export enum ExtensionMode {
+        /**
+         * The extension is installed normally (for example, from the marketplace
+         * or VSIX) in the editor.
+         */
+        Production = 1,
+
+        /**
+         * The extension is running from an `--extensionDevelopmentPath` provided
+         * when launching the editor.
+         */
+        Development = 2,
+
+        /**
+         * The extension is running from an `--extensionTestsPath` and
+         * the extension host is running unit tests.
+         */
+        Test = 3,
+    }
+
+    /**
+     * An extension context is a collection of utilities private to an
+     * extension.
      *
-     * An instance of a `PluginContext` is provided as the first
-     * parameter to the `start` of a plug-in.
+     * An instance of an `ExtensionContext` is provided as the first
+     * parameter to the `activate`-call of an extension.
      */
-    export interface PluginContext {
+    export interface ExtensionContext {
 
         /**
          * An array to which disposables can be added. When this
          * extension is deactivated the disposables will be disposed.
+         *
+         * *Note* that asynchronous dispose-functions aren't awaited.
          */
-        subscriptions: { dispose(): any }[];
+        readonly subscriptions: { dispose(): any }[];
 
         /**
          * A memento object that stores state in the context
          * of the currently opened {@link workspace.workspaceFolders workspace}.
          */
-        workspaceState: Memento;
+        readonly workspaceState: Memento;
 
         /**
          * A memento object that stores state independent
          * of the current opened {@link workspace.workspaceFolders workspace}.
          */
-        globalState: Memento & {
+        readonly globalState: Memento & {
             /**
              * Set the keys whose values should be synchronized across devices when synchronizing user-data
              * like configuration, extensions, and mementos.
@@ -3556,19 +3545,21 @@ export module '@theia/plugin' {
         };
 
         /**
-         * A storage utility for secrets.
+         * A storage utility for secrets. Secrets are persisted across reloads and are independent of the
+         * current opened {@link workspace.workspaceFolders workspace}.
          */
         readonly secrets: SecretStorage;
 
         /**
-         * The absolute file path of the directory containing the extension.
+         * The uri of the directory containing the extension.
          */
-        extensionPath: string;
+        readonly extensionUri: Uri;
 
         /**
-         * The uri of the directory containing the extension.
+         * The absolute file path of the directory containing the extension. Shorthand
+         * notation for {@link TextDocument.uri ExtensionContext.extensionUri.fsPath} (independent of the uri scheme).
          */
-        readonly extensionUri: Uri;
+        readonly extensionPath: string;
 
         /**
          * Gets the extension's environment variable collection for this workspace, enabling changes
@@ -3579,64 +3570,79 @@ export module '@theia/plugin' {
         /**
          * Get the absolute path of a resource contained in the extension.
          *
+         * *Note* that an absolute uri can be constructed via {@linkcode Uri.joinPath} and
+         * {@linkcode ExtensionContext.extensionUri extensionUri}, e.g. `vscode.Uri.joinPath(context.extensionUri, relativePath);`
+         *
          * @param relativePath A relative path to a resource contained in the extension.
          * @return The absolute path of the resource.
          */
         asAbsolutePath(relativePath: string): string;
 
+        /**
+         * The uri of a workspace specific directory in which the extension
+         * can store private state. The directory might not exist and creation is
+         * up to the extension. However, the parent directory is guaranteed to be existent.
+         * The value is `undefined` when no workspace nor folder has been opened.
+         *
+         * Use {@linkcode ExtensionContext.workspaceState workspaceState} or
+         * {@linkcode ExtensionContext.globalState globalState} to store key value data.
+         *
+         * @see {@linkcode FileSystem workspace.fs} for how to read and write files and folders from
+         *  an uri.
+         */
+        readonly storageUri: Uri | undefined;
+
         /**
          * An absolute file path of a workspace specific directory in which the extension
          * can store private state. The directory might not exist on disk and creation is
          * up to the extension. However, the parent directory is guaranteed to be existent.
          *
-         * Use [`workspaceState`](#PluginContext.workspaceState) or
-         * [`globalState`](#PluginContext.globalState) to store key value data.
+         * Use {@linkcode ExtensionContext.workspaceState workspaceState} or
+         * {@linkcode ExtensionContext.globalState globalState} to store key value data.
          *
-         * @deprecated Use {@link PluginContext.storageUri storageUri} instead.
+         * @deprecated Use {@link ExtensionContext.storageUri storageUri} instead.
          */
-        storagePath: string | undefined;
+        readonly storagePath: string | undefined;
 
         /**
-         * The uri of a workspace specific directory in which the extension
-         * can store private state. The directory might not exist and creation is
+         * The uri of a directory in which the extension can store global state.
+         * The directory might not exist on disk and creation is
          * up to the extension. However, the parent directory is guaranteed to be existent.
-         * The value is `undefined` when no workspace nor folder has been opened.
          *
-         * Use [`workspaceState`](#PluginContext.workspaceState) or
-         * [`globalState`](#PluginContext.globalState) to store key value data.
+         * Use {@linkcode ExtensionContext.globalState globalState} to store key value data.
          *
-         * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from
+         * @see {@linkcode FileSystem workspace.fs} for how to read and write files and folders from
          *  an uri.
          */
-        readonly storageUri: Uri | undefined;
+        readonly globalStorageUri: Uri;
 
         /**
          * An absolute file path in which the extension can store global state.
          * The directory might not exist on disk and creation is
          * up to the extension. However, the parent directory is guaranteed to be existent.
          *
-         * Use [`globalState`](#PluginContext.globalState) to store key value data.
+         * Use {@linkcode ExtensionContext.globalState globalState} to store key value data.
          *
-         * @deprecated Use {@link PluginContext.globalStorageUri globalStorageUri} instead.
+         * @deprecated Use {@link ExtensionContext.globalStorageUri globalStorageUri} instead.
          */
         readonly globalStoragePath: string;
 
         /**
-         * The uri of a directory in which the extension can store global state.
-         * The directory might not exist on disk and creation is
-         * up to the extension. However, the parent directory is guaranteed to be existent.
-         *
-         * Use [`globalState`](#PluginContext.globalState) to store key value data.
+         * The uri of a directory in which the extension can create log files.
+         * The directory might not exist on disk and creation is up to the extension. However,
+         * the parent directory is guaranteed to be existent.
          *
-         * @see [`workspace.fs`](#FileSystem) for how to read and write files and folders from
+         * @see {@linkcode FileSystem workspace.fs} for how to read and write files and folders from
          *  an uri.
          */
-        readonly globalStorageUri: Uri;
+        readonly logUri: Uri;
 
         /**
          * An absolute file path of a directory in which the extension can create log files.
          * The directory might not exist on disk and creation is up to the extension. However,
          * the parent directory is guaranteed to be existent.
+         *
+         * @deprecated Use {@link ExtensionContext.logUri logUri} instead.
          */
         readonly logPath: string;
 
@@ -3648,17 +3654,9 @@ export module '@theia/plugin' {
         readonly extensionMode: ExtensionMode;
 
         /**
-         * The current extension instance.
+         * The current `Extension` instance.
          */
-        readonly extension: Plugin<any> | undefined;
-
-        /**
-         * The uri of a directory in which the extension can create log files. The directory might
-         * not exist on disk and creation is up to the extension. However, the parent directory is
-         * guaranteed to be existent.
-         * see - workspace.fs for how to read and write files and folders from an uri.
-         */
-        readonly logUri: Uri;
+        readonly extension: Extension<any>;
     }
 
     /**
@@ -4874,7 +4872,7 @@ export module '@theia/plugin' {
         /**
          * Registers a webview panel serializer.
          *
-         * Plugins that support reviving should have an `"onWebviewPanel:viewType"` activation event and
+         * Extensions that support reviving should have an `"onWebviewPanel:viewType"` activation event and
          * make sure that {@link registerWebviewPanelSerializer registerWebviewPanelSerializer} is called during activation.
          *
          * Only a single serializer may be registered at a time for a given `viewType`.
@@ -8250,7 +8248,7 @@ export module '@theia/plugin' {
     }
 
     /**
-     * The completion item provider interface defines the contract between plugin and IntelliSense
+     * The completion item provider interface defines the contract between extensions and IntelliSense
      *
      * Providers can delay the computation of the [`detail`](#CompletionItem.detail)
      * and [`documentation`](#CompletionItem.documentation) properties by implementing the
@@ -10079,7 +10077,7 @@ export module '@theia/plugin' {
          * @return A hover or a thenable that resolves to such. The lack of a result can be
          * signaled by returning `undefined` or `null`.
          */
-        provideHover(document: TextDocument, position: Position, token: CancellationToken | undefined): ProviderResult<Hover>;
+        provideHover(document: TextDocument, position: Position, token: CancellationToken): ProviderResult<Hover>;
     }
 
     /**
@@ -11782,7 +11780,7 @@ export module '@theia/plugin' {
         /**
          * Fetches all tasks available in the systems. This includes tasks
          * from `tasks.json` files as well as tasks from task providers
-         * contributed through extensions and plugins.
+         * contributed through extensions.
          *
          * @param filter a filter to filter the return tasks.
          */