Skip to content

WTI‐API Server Code Debugging

Jump to bottom
John Clevenger edited this page Jan 13, 2025 · 1 revision

Overview

The page at WTI-UI Code Debugging describes how to use a browser's built-in debugger to step through code on the WTI-UI (team browser) side. However, sometimes it is desirable to be able to step through WTI code on the Server side -- that is, to debug code in the WTI-API project.

Since the WTI-API (Server) code is basically just a Java project, it is possible to run it inside any Java-compatible debugger -- for example, using jdb, the Java Debugger, or even using the debugger built into various IDEs. Because the primary development IDE used by PC2 developers is Eclipse, this page provides instructions on how to step through (debug) WTI-API code in the Eclipse debugger. Similar instructions are highly likely to work for other IDEs.

Setup

  • Open Eclipse on the PC2v9 project where you wish to debug the WTI Server.

  • Create a new "Debug Configuration":

    • Select Run>DebugConfigurations...
    • Either:
      • Select New launch Configuration (small "+" icon at the top left), or
      • Select an existing debug configuration and then select Duplicate Currently Selected Launch Configuration (small icon in the top menu).
    • Enter a new name for the Debug Configuration in the Name field, such as "DebugWTIServer".
    • Enter "WTI-API" in the Project field (or use the "Browse" button to navigate to and select the WTI-API project).
    • Enter "config.JettyConfig" in the Main class field ("config.JettyConfig" is the name of the WTI-API class containing the WTI Server's "main" method). If you want the WTI Server to stop (take a breakpoint) as soon as it starts, check the Stop in main checkbox. (Otherwise, you will have to set breakpoints wherever you want it to break.)
    • Select the Arguments tab.
    • In the VM arguments field, enter "-Djdk.crypto.KeyAgreement.legacyKDF=true -Xms64M -Xmx2048M". Note that these JVM arguments are precisely what appear in the "pc2wti" script which is normally used to start the WTI Server. (You can change the stack (-Xms) and memory (-Xmx) limits, but you must include the "-Djdk.crypto.KeyAgreement.legacyKDR=true" argument. This is because PC2 modules use a crypto algorithm that has been deprecated (although not removed from the JVM); this argument is required to get the JVM to allow the PC2 crypto algorithm to work.)
    • Clear any arguments that appear in the Program arguments field.
    • Click Apply to save the configuration details.

Execution

  • If there exists a "logs" folder under the WTI-API project in Eclipse, delete it (this folder contains logs from some previous run of WTI in Eclipse; you probably want to start with clean logs...)
  • Start a PC2 Server (you can do this either inside of Eclipse, or from a separate PC2 distribution -- but if you do the latter you should make sure that the external distribution matches the WTI version that you'll be running (debugging) within Eclipse).
  • In Eclipse, select your "DebugWTIServer" debug configuration (using the Run>DebugConfigurations... menu item), then click the Debug button. This starts the WTI-API project (server) running inside the Eclipse debugger.

You can set breakpoints in the WTI code by opening the source code file for a class and double-clicking in the narrow column just to the left of the source code line number (breakpoints show as a small blue "dot" in that column). (Note: if you are running the PC2 Server from an external distribution [i.e. outside of Eclipse], it does no good to set breakpoints in the PC2v9 project code in Eclipse; only breakpoints which get set in the WTI-API project code will have any effect.)

You can trace through the WTI code using the standard Eclipse Debugger functions:

  • F5: step into the next function.
  • F6: step over (execute) the next statement.
  • F7: step return (execute the current function untill it returns).
  • F8: resume (continue execution).
  • etc...

Additional Notes

Normally, once the WTI Server is running you should be able to open a browser pointing to "http://<ip>:8080" and get back the PC2 Login page. (Note that "<ip>" represents the IP address of the machine on which the WTI Server is running; if you're running everything on a single machine then "http://localhost:8080" should work.)

If instead of the PC2 Login page you get back a message like:

HTTP ERROR 404
Problem accessing /. Reason:
    Not Found
Powered by Jetty:// 9.4.14.v20181114

then it means that you have accessed the WTI Server (since the reply came from "Jetty"), but that the Jetty server doesn't know how to serve the PC2 Login page defined in the WTI-UI project.

The most likely reason for this problem is that there is no "WTI-UI" web content underneath the WTI-API project from which you're executing the WTI-API Server in Eclipse. This is in fact the standard configuration: when the PC2 Project is built (whether in Eclipse on your local machine or on GitHub), it does not normally include the WTI-UI project as part of the WTI-API project -- because they are structured as separate projects. Rather, the PC2 "build" process builds the WTI-UI project and then copies it into the WTI "WebTeamInterface-x.x" jar file. This makes the WTI-UI project available when running the WTI Server from a PC2 distribution -- but it does NOT automatically mean the WTI-UI is accessible from within the WTI-API project in Eclipse.

To fix this problem, open any PC2 distribution that is compatible with the WTI-API project you are trying to debug. Unzip the "WebTeamInterface-x.x-.zip" (or .tar.gz) file, then go into the resulting "WebTeamInterface-x.x" folder then into the "WebContent" folder beneath that. Copy the "WTI-UI" folder found there into the "WebContent" folder found directly under the WTI-API project in Eclipse. (You might also be able to find the "WTI-UI" folder under the "build/WebContent" folder beneath the WTI-API project in Eclipse; depending on how you executed the most recent build of PC2 in Eclipse, the build process may have left the WTI-UI folder there. If so, copying that WTI-UI folder from "WTI-API/build/WebContent" to the WebContent folder directly beneath the WTI-API project itself should also work.)

Refreshing the team browser page (or opening a new browser window to "http://localhost:8080") should now display the PC2 Login page (unless the WTI Server running in Eclipse has been stopped at a breakpoint, in which case you'll have to "resume" the WTI Server in the debugger in order to see the login page).

See Also

PC2 Logo

Clone this wiki locally