docs: clarify java setup (#5502)

* docs: Update java-setup.md and Apex package.nls.json for settings text Update Java home Settings to help Windows users in the extension. --------- Co-authored-by: Daphne Yang <139700604+daphne-sfdc@users.noreply.github.com> Co-authored-by: Sonal Budhiraja <57969266+sbudhirajadoc@users.noreply.github.com>
forcedotcom · Mar 15, 2024 · c2019fa · c2019fa
1 parent 4c2c6a4
commit c2019fa
Show file tree

Hide file tree

Showing 3 changed files with 55 additions and 73 deletions.
diff --git a/docs/_articles/en/vscode-desktop/java-setup.md b/docs/_articles/en/vscode-desktop/java-setup.md
@@ -5,66 +5,23 @@ lang: en
 
 The Apex Language Server, shipped as part of the Salesforce Apex Extension for VS Code, depends on the Java Platform, Standard Edition Development Kit (JDK). It requires an installation of either JDK version 17 (Recommended), or JDK version 11. By default, the extension attempts to locate your local Java installation by looking for a `JAVA_HOME` or `JDK_HOME` environment variable on your computer. If the extension can't find your Java installation, or if you want it to use a different installation, change the `salesforcedx-vscode-apex.java.home` setting.
 
-1. Select **File** > **Preferences** > **Settings** (Windows or Linux) or **Code** > **Preferences** > **Settings** (macOS).
-2. Search for `apex`.
-3. Change the `salesforcedx-vscode-apex.java.home` setting to the full pathname of your Java Runtime. Do **not** set it to the Java executable itself. Note that this pathname can't point to a location inside your project folder.
-
-![Apex Java Setting](./images/apex-java-home-setting.png)
-
-Below you'll find instructions on how to download and configure different versions of Java.
+## Download and Install JDK
+You can download the JDK from one of these locations.
 
-## Adoptium
+### Adoptium
 
 [Adoptium](https://adoptium.net) provides prebuilt OpenJDK binaries for free without authentication or complications.
 
-1. Navigate to [Adoptium](https://adoptium.net/?variant=openjdk17)
-2. Select **Temurin 17 (LTS)**
+1. Navigate to [Adoptium](https://adoptium.net/?variant=openjdk17).
+2. Select **Temurin 17 (LTS)**.
 3. Click the **Latest Release** button to download.
 4. After the file has downloaded, open it and complete the installation steps.
 
-Inside Visual Studio Code, set `salesforcedx-vscode-apex.java.home` to one of the following values or to wherever your have installed JDK 17. For example:
-
-MacOS:
-
-For Mac OS X 10.5 or later, run `/usr/libexec/java_home` in your Terminal to get the default JDK location. To find all installed JDKs, use `/usr/libexec/java_home -V`.
-
-```json
-{
-  "salesforcedx-vscode-apex.java.home": "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home"
-}
-```
-
-Windows:
-
-```json
-{
-  "salesforcedx-vscode-apex.java.home": "C:\\Program Files\\Eclipse Adoptium\\jdk-17.0.2.8-hotspot"
-}
-```
-
-### Linux
-
-Pop! OS 20.04 (installation via aptitude):
-
-```json
-{
-  "salesforcedx-vscode-apex.java.home": "/usr/lib/jvm/java-17-openjdk-amd64"
-}
-```
-
-Arch Linux (installation via AUR using package `jdk17-adoptopenjdk`):
-
-```json
-{
-  "salesforcedx-vscode-apex.java.home": "/usr/lib/jvm/java-17-adoptopenjdk"
-}
-```
-
-## Zulu
+### Zulu
 
 Zulu Java builds are TCK-tested and free to download and use without restrictions.
 
-1. Navigate to the [Zulu download page](https://www.azul.com/downloads/zulu/)
+1. Navigate to the [Zulu download page](https://www.azul.com/downloads/zulu/).
 2. Click the **Choose Your Download** button.
 3. Select Java Version **Java 17 (LTS)**.
 4. Select your OS.
@@ -73,54 +30,79 @@ Zulu Java builds are TCK-tested and free to download and use without restriction
 7. Download the installer.
 8. Once the file is downloaded open it and complete the installation steps.
 
-Inside Visual Studio Code, set `salesforcedx-vscode-apex.java.home` to one of the following values.
+### Oracle Java 17 (Officially Tested)
+
+1. Navigate to the [download page](https://www.oracle.com/java/technologies/downloads/).
+2. Navigate to **Java SE Development Kit 17.0.10 downloads**.
+3. Click the download link that applies to your OS.
+4. If prompted to log in, use your Oracle account.
+5. Once the file is downloaded open it and complete the installation steps.
+
+**Note**: Installing from the executable correctly installs Java in the standard Java Home path (C:\Program Files\) making setting the JDK path straightforward.
+
+## Update JDK Path
+
+Update the salesforcedx-vscode-apex.java.home setting to the full pathname of the Java Runtime that is used to launch your Apex server.
+
+1. Select **File** > **Preferences** > **Settings** (Windows or Linux) or **Code** > **Settings...** > **Settings** (macOS).
+2. Search for `apex`.
+3. Change the `salesforcedx-vscode-apex.java.home` setting to the full pathname of your Java Runtime. Do not set it to the Java executable itself.
+
+**Note**: This pathname can’t point to a location inside your project folder. Also note that backslashes must be escaped on Windows.
+
+![Apex Java Setting](./images/apex-java-home-setting.png)
 
-MacOS:
+Some examples of folder paths to the Java 11 or Java 17 runtime:
 
-For Mac OS X 10.5 or later, run `/usr/libexec/java_home` in your Terminal to get the default JDK location. To find all installed JDKs, use `/usr/libexec/java_home -V`.
+**MacOS**:
 
 ```json
 {
-  "salesforcedx-vscode-apex.java.home": "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home"
+  "salesforcedx-vscode-apex.java.home": "/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home"
 }
 ```
 
-Windows:
+**Windows**:
 
 ```json
 {
-  "salesforcedx-vscode-apex.java.home": "C:\\Program Files\\Zulu\\zulu-17"
+  "salesforcedx-vscode-apex.java.home": "C:\\Program Files\\Eclipse Adoptium\\jdk-17.0.2.8-hotspot"
 }
 ```
 
-## Oracle Java 17 (Officially Tested)
-
-1. Navigate to the [download page](https://www.oracle.com/java/technologies/downloads/)
-2. Navigate to **Java SE Development Kit 17.0.2 downloads**.
-3. Click the download link that applies to your OS
-4. If prompted to log in, use your Oracle account.
-5. Once the file is downloaded open it and complete the installation steps.
-
-Inside Visual Studio Code, set `salesforcedx-vscode-apex.java.home` to one of the following values.
+**Linux**:
 
-MacOS:
-
-For Mac OS X 10.5 or later, run `/usr/libexec/java_home` in your Terminal to get the default JDK location. To find all installed JDKs, use `/usr/libexec/java_home -V`.
+**Pop! OS 20.04 (installation via aptitude)**:
 
 ```json
 {
-  "salesforcedx-vscode-apex.java.home": "/Library/Java/JavaVirtualMachines/jdk-17.0.2.jdk/Contents/Home"
+  "salesforcedx-vscode-apex.java.home": "/usr/lib/jvm/java-17-openjdk-amd64"
 }
 ```
 
-Windows:
+**Arch Linux (installation via AUR using package `jdk17-adoptopenjdk`)**:
 
 ```json
 {
-  "salesforcedx-vscode-apex.java.home": "C:\\Program Files\\Java\\jdk17.0.2"
+  "salesforcedx-vscode-apex.java.home": "/usr/lib/jvm/java-17-adoptopenjdk"
 }
 ```
 
+## Troubleshooting Tips
+
+* If you see an error message that your Java version is not supported, open the Output tab on the bottom panel of VS Code. Filter by 'Apex'. Also review the 'Problems' tab to see that the Apex Language Server has been able to start.
+* For Windows, ensure you are escaping the path to your JDK location appropriately.
+
+  If your Java version is located at the following path:
+
+              `C:\Program Files\Java\jdk-17`
+  Your Java Home path should like this:
+
+              `C:\\Program Files\\Java\\jdk-17`
+
+
+
+
 ## Advanced Setup
 
 By default, a JVM allocates up to one fourth of the system's physical memory to the Apex Language Server process. If you are working on projects with more memory requirements, use the `salesforcedx-vscode-apex.java.memory` setting to override the defaults. Use this setting to specify the maximum size of memory allocation in megabytes and in multiples of 1024.

diff --git a/packages/salesforcedx-vscode-apex/package.json b/packages/salesforcedx-vscode-apex/package.json
@@ -137,7 +137,7 @@
         },
         "salesforcedx-vscode-apex.java.home": {
           "default": null,
-          "description": "%java_home_description%",
+          "markdownDescription": "%java_home_description%",
           "type": "string"
         },
         "salesforcedx-vscode-apex.java.memory": {

diff --git a/packages/salesforcedx-vscode-apex/package.nls.json b/packages/salesforcedx-vscode-apex/package.nls.json
@@ -19,7 +19,7 @@
   "apex_verbose_level_trace_description": "Output everything, including details about notifications and responses received by the client, and requests sent by the server.",
   "configuration_title": "Salesforce Apex Configuration",
   "go_to_definition_title": "Go to Definition",
-  "java_home_description": "Specifies the folder path to the Java 11 or Java 17 runtime used to launch the Apex Language Server (for example, /Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home).",
+  "java_home_description": "Specifies the folder path to the Java 11 or Java 17 runtime used to launch the Apex Language Server. Note on Windows the backslashes must be escaped.\n\nMac Example: `/Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home`\n\nWindows Example: `C:\\\\Program Files\\\\Zulu\\\\zulu-17`\n\nLinux Example: `/usr/lib/jvm/java-17-openjdk-amd64`",
   "java_memory_description": "Specifies the amount of memory allocation to the Apex Language Server in MB, or null to use the system default value.",
   "refresh_test_title": "Refresh Tests",
   "run_single_test_title": "Run Single Test",