cds debug for Java

tools/cds-cli.md

@@ -546,17 +546,41 @@ There a couple of shortcuts and convenience functions:
 :::
 
 
-## Debugging with `cds debug` <Beta /> {.nodejs}
+## Debugging with `cds debug` <Beta /> {#cds-debug}
 
-`cds debug` lets you debug Node.js applications in Chrome DevTools running locally or in Cloud Foundry.
+`cds debug` lets you debug applications running locally or remotely on Cloud Foundry.
+Local applications will be started in debug mode, while (already running) remote applications are put into debug mode.
 
-To debug remote applications in the currently targeted CF space, run:
+To debug a application on Cloud Foundry, make sure
+- to be logged in to the space where the application is deployed to,
+- that you have developer permissions in the space
+- that the app is running and [reachable through SSH](https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html#check-ssh-permissions).
+
+Effectively, run:
+```sh
+cf login                   # select the correct org and space here
+cf ssh-enabled <app-name>  # to check if SSH is enabled
+```
+
+::: tip Scale to one application instance only
+We recommend to only scale to _one_ app instance on SAP BTP Cloud Foundry, as then your request is guaranteed to hit this one instance.
+If you scale out to more instances, only some of your requests will hit the instance that the debugger is connected to. This can result in 'missed breakpoints'.
+
+However, it's possible to [route a request to a specific instance](https://docs.cloudfoundry.org/devguide/deploy-apps/routes-domains.html#surgical-routing), which is useful if you can't reduce the number of app instances.
+:::
+
+
+### Node.js Applications
+
+To debug remote Node.js applications in the currently targeted CF space, run:
 
 <pre class="log">
-<span class="cwd">$</span> <span class="cmd">cds</span> <span class="args">debug</span> <span class="options">bookshop-srv</span>
+<span class="cwd">$</span> <span class="cmd">cds</span> <span class="args">debug</span> <span class="options">&lt;app-name&gt;</span>
 
-Opening SSH tunnel for CF app 'bookshop-srv'
+Opening SSH tunnel on 9229:127.0.0.1:9229
 Opening Chrome DevTools at devtools://devtools/bundled/inspector.html?ws=...
+
+> Keep this terminal open while debugging.
 </pre>
 
 This opens an [SSH tunnel](https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html), puts the application in debug mode, and connects and opens the [debugger of Chrome DevTools](https://developer.chrome.com/docs/devtools/javascript).
@@ -575,11 +599,51 @@ Opening Chrome DevTools at devtools://devtools/bundled/inspector.html?ws=...
 [cds] - ...
 </pre>
 
-::: tip Scale to one application instance only
-We recommend to only scale to _one_ app instance on SAP BTP Cloud Foundry, as then your request is guaranteed to hit this one instance.
-If you scale out to more instances, only some of your requests will hit the instance that the debugger is connected to. This can result in 'missed breakpoints'.
+::: details Under the hoods, these commands are executed:
+```sh
+cf ssh <app> -c "kill -usr1 `pidof node`"
+cf ssh -N -L 9229:localhost:9229 <app>
+```
+:::
 
-However, it's possible to [route a request to a specific instance](https://docs.cloudfoundry.org/devguide/deploy-apps/routes-domains.html#surgical-routing), which is useful if you can't reduce the number of app instances.
+### Java Applications <Since version="8.7.0" of="@sap/cds-dk" />
+
+To debug remote Java applications in the currently targeted CF space, run:
+
+<pre class="log">
+<span class="cwd">$</span> <span class="cmd">cds</span> <span class="args">debug</span> <span class="options">&lt;app-name&gt;</span>
+...
+Debugging has been started.
+Address : 8000
+
+Opening SSH tunnel on 8000:127.0.0.1:8000
+
+> Keep this terminal open while debugging.
+</pre>
+
+This opens an [SSH tunnel](https://docs.cloudfoundry.org/devguide/deploy-apps/ssh-apps.html) and puts the application in debug mode.
+
+Afterwards, you need to connect a debugger from your IDE to it at the given port.  In VS Code, for example, add a launch configuration like this one:
+
+::: code-group
+```json [.vscode/launch.json]
+{
+  "type": "java",
+  "name": "Attach to Remote Java App",
+  "request": "attach",
+  "hostName": "localhost",
+  "port": "8000"
+}
+```
+:::
+
+Make sure the port matches to what the debug tunnel uses (see the message in the terminal). The default port is `8000`.
+
+::: details Under the hoods, these commands are executed:
+```sh
+cf ssh <app> -c "~/app/META-INF/.sap_java_buildpack/sap_machine_jre/bin/jcmd `pidof java` VM.start_java_debugging"
+cf ssh -N -L 8000:localhost:8000 <app>
+```
 :::