Merge branch 'main' into jep-486

Author: lahodaj

.github/workflows/main.yml

@@ -55,21 +55,7 @@ jobs:
         uses: actions/checkout@v4
         with:
           persist-credentials: false
-          submodules: false
-
-      - name: Checkout NetBeans
-        uses: actions/checkout@v4
-        with:
-          repository: apache/netbeans
-          path: netbeans
-          ref: 23
-
-      - name: Checkout NetBeans l10n
-        uses: actions/checkout@v4
-        with:
-          repository: apache/netbeans-l10n
-          path: netbeans-l10n
-          ref: ece00239dc7a208fba60703c2256ffd818da1646
+          submodules: true
 
       - name: Apply NetBeans patches
         run: ant apply-patches

.gitignore

@@ -1,6 +1,4 @@
 build/
-netbeans/
-netbeans-l10n/
 .DS_STORE
 .idea/
 *.iml

.gitmodules

@@ -0,0 +1,6 @@
+[submodule "netbeans-l10n"]
+	path = netbeans-l10n
+	url = https://github.com/apache/netbeans-l10n.git
+[submodule "netbeans"]
+	path = netbeans
+	url = https://github.com/apache/netbeans.git

BUILD.md

@@ -27,29 +27,21 @@
 
 ## Prerequisities
 
-- JDK, version 11 or later upto JDK 22
+- JDK, version 17 or later
 - Ant, latest version
 - Maven, latest version
 - Node.js, latest LTS (to build VSIX)
 
 ## Fetching and building the code
 
 ```bash
-$ git clone https://github.com/oracle/javavscode.git
-$ cd javavscode/
-$ git clone https://github.com/apache/netbeans.git
-$ cd netbeans/
-$ git checkout 23
-$ cd ..
-$ git clone https://github.com/apache/netbeans-l10n.git
-$ cd netbeans-l10n
-$ git checkout ece00239dc7a208fba60703c2256ffd818da1646 # head commit in master
-$ cd ..
+$ git clone --recurse-submodules https://github.com/oracle/javavscode.git
+$ cd javavscode
 # the following target requires git executable to be on PATH:
 $ ant apply-patches
 $ ant build-netbeans
 
-#Note if you do not wish to have l10n in scope then add no-l10n before any ant invocation target at beginning as below, by default l10n is enabled
+# Note if you do not wish to have l10n in scope then add no-l10n before any ant invocation target at beginning as below, by default l10n is enabled
 $ ant no-l10n apply-patches
 $ ant no-l10n build-netbeans
 ```
@@ -67,26 +59,82 @@ The typical file name is `oracle-java-0.1.0.vsix`.
 
 ### Building for Development
 
-If you want to develop the extension, use these steps for building instead:
-
-```bash
-ant build-lsp-server
-```
-
-This target is faster than building the `.vsix` file. Find the instructions
-for running and debugging below.
-
-### Cleaning
+If you're developing the extension, follow these steps to build the project for faster iterations without packaging a `.vsix` file:
+
+1. Run the following command to build the Language Server Protocol (LSP) server:
+   ```bash
+   $ ant build-lsp-server
+   ```
+2. Navigate to the `vscode` folder:
+   ```bash
+   $ cd vscode
+   ```
+3. Install the necessary Node.js dependencies:
+   ```bash
+   $ npm install
+   ```
+4. Start the build watcher to automatically rebuild the extension on file changes:
+   ```bash
+   $ npm run watch
+   ```
+
+This process is faster than packaging the extension as a `.vsix` file, allowing for quicker development cycles.
+
+### Debugging the Extension
+
+Follow these steps to debug both the extension's TypeScript code and the NetBeans server code:
+
+#### 1. Debugging TypeScript Code (VS Code Extension)
+1. Open the `vscode` folder in VS Code.
+2. Press `F5` to launch and debug the extension.
+
+#### 2. Debugging NetBeans Code (Server Side)
+1. Open the **Command Palette** using `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS).
+2. Search for **Preferences: Open User Settings (JSON)** and select it.
+3. Locate or add the `jdk.serverVmOptions` setting in the JSON file and append the following arguments:
+   ```json
+   "jdk.serverVmOptions": [
+      "-Xdebug",
+      "-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=8000"
+   ]
+   ```
+4. Start your debugging session. The NetBeans server will suspend execution and wait for a remote debugger to connect at port `8000`.
+
+[NOTE: If you are using multiple profiles in VS Code, then set above configuration in appropriate profile
+
+This configuration will enable you to debug both the extension’s TypeScript code and the NetBeans server-side code.
+
+#### To enable Netbeans logs in the output channel of VS Code IDE
+
+##### Option 1: Enable `jdk.verbose` Logging
+1. Open the **Command Palette** using `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS).
+2. Search for **Preferences: Open User Settings (JSON)** and select it.
+3. In the settings JSON file, add or update the following setting:
+   ```json
+   "jdk.verbose": true
+   ```
+
+##### Option 2: Enable NetBeans Logs via JVM Options
+1. Open the **Command Palette** using `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS).
+2. Search for **Preferences: Open User Settings (JSON)** and select it.
+3. Locate or add the `jdk.serverVmOptions` setting and append the following argument to the array:
+   ```json
+   "jdk.serverVmOptions": ["-J-Dnetbeans.logger.console=true"]
+   ```
+
+Both options will enable logging from the NetBeans server in the VS Code Output Channel.
+
+### Cleaning the Extension
 
 Often it is also important to properly clean everything. Use:
 
 ```bash
-ant clean-vscode-ext
-cd netbeans/
-netbeans$ ant clean
+$ ant clean-vscode-ext
+$ cd netbeans/
+$ ant clean
 ```
 
-### Testing
+### Testing the Extension
 
 The `java.lsp.server` module has classical (as other NetBeans modules) tests.
 The most important one is [ServerTest](https://github.com/apache/netbeans/blob/master/java/java.lsp.server/test/unit/src/org/netbeans/modules/java/lsp/server/protocol/ServerTest.java)
@@ -107,3 +155,29 @@ $ npm_config_https_proxy=http://your.proxy.com:port ant test-vscode-ext
 
 when executing the tests for the first time. That shall overcome the proxy
 and download an instance of `code` to execute the tests with.
+
+## Working with git submodules
+
+This project uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) . In particular netbeans and netbeans-l10n are submodules pointing to specific commits in their respective repositories .
+
+### Switching Branches 
+
+Add the --recurse-submodules  flag to the git checkout command to update the submodules during the checkout.
+```bash
+git checkout --recurse-submodules <branch_name>
+```
+Note:- Merging branches with submodules pointing to different commits can be tricky. Refer the [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for more details on the same.
+
+### Changing submodules versions 
+
+```bash
+# Fetching changes from remote submodule repositories 
+git submodule update --remote   
+# Changing the submodule version
+cd netbeans
+git checkout <commit_hash>
+cd ..
+# Committing the submodule version 
+git add netbeans
+git commit -m "Updated netbeans"
+```

README.md

@@ -40,14 +40,14 @@ Java Platform extension from Oracle brings full featured development support (ed
     - For more information, see the section [Selecting the JDK](#selecting-the-jdk).
 4. Use any one of the following ways to start coding, compiling and debugging in Java.
     - Simply create a new Java class with `public static void main(String[] args)` method.
-    - Use the __Java: New From Template...__ command to create a new Java file.
+    - Use the __Java: New File...__ command to create a new Java file.
     - Use the __Java: New Project...__ command to create a new project.
     - Open the folder with existing __Maven__ or __Gradle__ project files (_pom.xml_ or _build.gradle, gradle.properties_).
 
 ## Supported Actions
 In the VS Code command palette :
 * __Java: New Project...__ allows creation of new Maven or Gradle project 
-* __Java: New from Template...__ add various files to currently selected open project. Files are:
+* __Java: New File...__ add various files to currently selected open project. Files are:
     * Java - broad selection of various predefined Java classes
     * Unit tests - JUnit and TestNG templates for test suites and test cases
     * Other - various templates for Javascript, JSON, YAML, properties, ... files
@@ -169,7 +169,7 @@ Oracle Java Platform extension provides Test Explorer view which allows to run a
 ### Localisation support
 Oracle Java Platform extension provides localisation support for _Japanese_ and _Simplified Chinese_. 
 To switch language `Go to command Palette->Configure display language` select `ja` for _Japanese_ or `zh-cn` for _Simplified Chinese_ 
-![localisation.gif](localisation.gif)
+![localisation.gif](vscode/images/localisation.gif)
 
 ## Selecting the JDK
 The JDK to build, run and debug projects is being searched in the following locations: