Developing APIs‎ > ‎Debugging‎ > ‎

Debugger

Prerequisites

Verify the following prerequisites before using the starting up and using the JavaScript debugger.

Jetty Version

You can use the debug services only on the single-user version demonstration package that is based on Jetty.

For more information about obtaining and installing this package, see Install the Single-User Demonstration Package.

If you are using Team Development, export your project and import it to your desktop. If you make changes, upload them.

JDK (not JRE)

Verify that you have completed the following:

  • Installed a full 1.8 JDK, not just a JRE.
  • Set the environment variable JAVA_HOME that points to your JDK installation directory.

(Windows) See the following image for an example (click the thumbnail to enlarge):

(Mac) Export the JAVA_HOME variable:

export JAVA_HOME="$(/usr/libexec/java_home -v 1.8)"

There are several ways to do this:
    • (Permanent for all programs) Add the variable to the .bash_profile in your home folder.
      Note: This is a hidden file.
    • (Permanent for the debug service) Add the variable to the <install-folder>/StartDebugService.sh file.
    • (Temporary) Type the variable in the terminal window before you start the debug service.

Startup

The debug service includes the following files:

  • StartDebug.bat
  • StartDebug.sh
  • StartDebugService.bat
  • StartDebugService.sh
  • Stop.bat
  • Stop.sh
  • StopDebugService.bat
  • StopDebugService.sh

    The following image shows these files in an example installation:

    Note: In this example, the "LAC 2695" is the unzipped Live API Creator install folder. The name of your file is different (and you can change the name).

    Start the API Server

    (Windows) Issue the following command:

    StartDebug.bat

    (Mac/Unix) Instead of the normal Start.bat/sh, issue the following command:

    sh StartDebug.sh

    Note: This command runs marginally slower and incurs the following security considerations.

    Security Considerations

    API Server uses Java Debug ports, which are not protected from intrusion. We recommend that you not use API Server in public networks (for example, the local coffee shop). You can use API Server safely behind home firewalls (for example, your router) and corporate networks.

    Start the Debug Service

    (Windows) Issue the following command:

    StartDebugService.bat

    (Mac/Unix) Issue the following command:

    sh StartDebugService.sh

    Set a Breakpoint

    Set a breakpoint by locating your code and clicking the margin at the left.

    Do not Exit the Debug Window

    Stay in the debug window for your debug session. Consider closing the left navigation bar to get space and remind you.

    For testing, run your application or open more browser tabs for the Live API Creator (for example, the REST Lab or Data Explorer).

    Server Busy  - Impacts other tabs

    When you are stopped at a breakpoint, the server is busy. Other browser tabs (for example, Data Explorer and the REST Lab) are responsive after execution proceeds.

    Only One Debug Session

    Connect only one browser tab to the JavaScript debugger. Connecting multiple sessions results in confusion about breakpoint handling. To verify the correct "tab" is attached to the debugger, verify the "connected" indicator in the top right (see the following image). You can always clear debugger state by restarting the debug service.

    Examine Variables

    When at a breakpoint, you can examine local variables you created, as well as API Creator-supplied variables, such as row. row is a context variable that is set when Live API Creator invokes JavaScript logic. You can also stop in loadable libraries, which (per JavaScript scoping) show variables from the calling logic:

    Step and Continue

    You can resume execution by clicking Step and Continue.

    Extra Step on First Entry

    When you first enter a method, you must complete an extra step. This is due to the packaging of your JavaScript code into internal functions, and indicates normal operation.

    JavaScript Optimization

    Live API Creator executes your JavaScript code using the Oracle Nashorn JavaScript engine. Nashorn optimally executes JavaScript. Nashorn generates an optimized compiled code from your JavaScript code and the system’s JVM executes this code.

    The JavaScript debugger:

    • Does not execute the lines of code that the Nashorn engine optimizes out.
    • Does not inspect the entities (variables, functions, and objects) that are part of code snippets in the debugger's variables pane.

    For example, in the following code snippet, the debugger does not execute line#2 and does not inspect the variable ‘foo’: 

    var bar = “John Doe”;
    var foo = 91; // This is unused and does not affect the outcome.
    var obj = {“name”: bar};
    var result = JSON.stringify(bar);
    print(result);