Guide users to setup correct mvn executable path

FAQ.md

@@ -0,0 +1,41 @@
+# FAQ
+
+## Requirements
+
+### Available Maven executable
+By default, `mvn` command is executed directly in the terminal, which requires `mvn` can be found in system envronment `PATH`.
+If you do not want to add it into `PATH`, you can specify maven executable path in settings:
+    ```
+    {
+        "maven.executable.path": "/some-path-to-maven-home/bin/mvn"
+    }
+    ```
+
+#### Possible error messages
+* Maven executable file not found/set.
+    ```
+    Command failed: mvn --version 'mvn' is not recognized as an internal or external command, operable program or batch file.
+    ```
+    In this case, please follow above instructions to set available maven executable path.
+
+
+* `M2_HOME` not correctly set.
+    ```
+    Error: Command failed: mvn help:effective-pom -f "xxxxxxxxxxxx\pom.xml" -Doutput="xxxxxxxxxxxxxxx\effective-pom.xml"
+    Error: M2_HOME is set to an invalid directory. 
+    M2_HOME = "xxxxxxxxx\apache-maven-3.3.9\bin" 
+    Please set the M2_HOME variable in your environment to match the 
+    location of the Maven installation
+    ```
+    In this case, please follow the error message to reset a correct `M2_HOME`.
+
+### Available Java Runtime (required by Maven)
+
+#### Possible error messages
+* `JAVA_HOME` not correctly set.
+    ```
+    The JAVA_HOME environment variable is not defined correctly
+    This environment variable is needed to run this program
+    NB: JAVA_HOME should point to a JDK not a JRE
+    ```
+    In this case, please specify a correct JAVA_HOME environment variable, or re-install JRE/JDK if necessary.

src/Utils.ts

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT license.
 
+import * as child_process from "child_process";
 import * as fse from "fs-extra";
 import * as http from "http";
 import * as https from "https";
@@ -333,4 +334,21 @@ export namespace Utils {
             return filepath;
         }
     }
+
+    export function getMavenVersion(): Promise<void> {
+        return new Promise<void>((resolve, reject) => {
+            const customEnv: {} = VSCodeUI.setupEnvironment();
+            const execOptions: child_process.ExecOptions = {
+                env: Object.assign({}, process.env, customEnv)
+            };
+            child_process.exec(
+                `${Utils.getMavenExecutable()} --version`, execOptions, (error: Error, _stdout: string, _stderr: string): void => {
+                    if (error) {
+                        reject(error);
+                    } else {
+                        resolve();
+                    }
+                });
+        });
+    }
 }

src/extension.ts

@@ -28,6 +28,7 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
     watcher.onDidDelete(() => mavenProjectsTreeDataProvider.refreshTree());
     context.subscriptions.push(watcher);
 
+    // register commands.
     ["clean", "validate", "compile", "test", "package", "verify", "install", "site", "deploy"].forEach((goal: string) => {
         context.subscriptions.push(TelemetryWrapper.registerCommand(`maven.goal.${goal}`, async (item: ProjectItem) => {
             await mavenProjectsTreeDataProvider.executeGoal(item, goal);
@@ -76,8 +77,9 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
         VSCodeUI.onDidCloseTerminal(closedTerminal);
     }));
 
-    // close all terminals with outdated Envs
+    // configuration change listener
     vscode.workspace.onDidChangeConfiguration((e: vscode.ConfigurationChangeEvent) => {
+        // close all terminals with outdated JAVA related Envs
         if (e.affectsConfiguration("maven.terminal.useJavaHome") || e.affectsConfiguration("maven.terminal.customEnv")) {
             VSCodeUI.closeAllTerminals();
         } else {
@@ -86,9 +88,33 @@ export async function activate(context: vscode.ExtensionContext): Promise<void>
                 VSCodeUI.closeAllTerminals();
             }
         }
+        checkMavenAvailablility();
     });
+
+    // check maven executable file
+    checkMavenAvailablility();
 }
 
 export function deactivate(): void {
     // this method is called when your extension is deactivated
 }
+
+// private helpers
+async function checkMavenAvailablility(): Promise<void> {
+    try {
+        await Utils.getMavenVersion();
+    } catch (error) {
+        const OPTION_SHOW_DETAILS: string = "Show details";
+        const OPTION_GUIDE: string = "Guidance";
+        const choiceForDetails: string = await vscode.window.showErrorMessage("Unable to execute Maven commands. Please make sure Maven is either in the PATH, or that 'maven.executable.path' is pointed to its installed location. Also make sure JAVA_HOME is specified either in environment variables or settings.", OPTION_SHOW_DETAILS);
+        if (choiceForDetails === OPTION_SHOW_DETAILS) {
+            const choiceForGuide: string = await vscode.window.showErrorMessage(error.message, OPTION_GUIDE);
+            if (choiceForGuide === OPTION_GUIDE) {
+                // open FAQ
+                const readmeFilePath: string = Utils.getPathToExtensionRoot("FAQ.md");
+                vscode.commands.executeCommand("markdown.showPreview", vscode.Uri.file(readmeFilePath));
+            }
+        }
+    }
+
+}

tslint.json

@@ -185,9 +185,9 @@
         "typedef": [
             true,
             "call-signature",
-            "arrow-call-signature",
+            // "arrow-call-signature",
             "parameter",
-            "arrow-parameter",
+            // "arrow-parameter",
             "property-declaration",
             "variable-declaration",
             "member-variable-declaration"