Debugger

You can examine the values of variables by stepping through your JavaScript code using the debug service (the debugger).
lac52
You can examine the values of variables by stepping through your JavaScript code using the debug service (the debugger).
Only with the single-user demonstration package of 
CA Live API Creator
 that is based on Jetty (demonstration package) includes the debugger. 
For more information about how to obtain and install the demonstration package, see Install the Single-User Demonstration Package.
In this article:
 
 
2
 
 
Set up to Use the Debugger
  1. Install the Java SE Development Kit (JDK) version that 
    CA Live API Creator
     supports.
    For more information:
  2. Create a 
    JAVA_HOME
     environment variable and set the value to point to the JDK installation directory.
    (Windows)
     Set the value for the 
    JAVA_HOME
     environment variable as the path to your JDK installation. If you did not change the path during installation, it is something like 
    C:\Program Files\Java\jdk1.8.0_92
    . If the path contains spaces, use the shortened path name, for example, 
    C:\PROGRA~2\Java\jdk1.8.0_92
    . Close and re-open any command line windows that you had open before you made these changes, since you cannot reload environment variables from an active command prompt. If the changes do not take effect after reopening the command window, restart Windows.
    (Mac)
     From terminal, set the 
    JAVA_HOME
     environment variable using the following command:
    export JAVA_HOME="$(/usr/libexec/java_home -v 1.8)"
    You can make the 
    JAVA_HOME
     environment variable available to all programs. Use one of the following methods:
    • (Permanent for all programs) Add the variable to the 
      .bash_profile
       in your home folder.
       
       This is a hidden file.
       
    • (Permanent for the debugger) Add the variable to the 
      <install-folder>/StartDebugService.sh
       file.
    • (Temporary) From Terminal, enter the variable before you start the debugger.
Use the Debugger
Use the following process to use the debugger in API Creator:
Start 
CA Live API Creator
 
The debugger 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:
In this example, the 
LAC 2695
 directory is the unzipped 
CA Live API Creator
 installation directory. The name of your file is different (and you can change the name).
 
Use the following process to start 
CA Live API Creator
:
Start API Server in Debug Mode
Prerequisite: 
You are not running API Server in normal mode.
API Server uses Java debug ports, which are not protected from intrusion. We recommend that you not use API Server in debug mode in public networks (for example, the local coffee shop).
(Windows) From a command prompt, issue the following command:
StartDebug.bat
(Mac/Unix) From a Terminal, issue the following command:
sh StartDebug.sh
API Server runs slower in debug mode than it does in normal mode.
API Server is started in debug mode.
Start the Debugger
(Windows) From a command prompt, issue the following command:
<install-folder>/StartDebugService.bat
(Mac/Unix) From Terminal, issue the following command:
sh <install-folder>/StartDebugService.sh
The Debugger is started.
Start the Debugger in API Creator
Prerequisites: 
If you are using team development, you have exported your API and imported it to your desktop. If you have made changes to the API while debugging, upload the API.
Best Practice: 
If you are testing, run your application or open more browser tabs for 
CA Live API Creator
 (for example, the REST Lab or Data Explorer).
Connect only one browser tab to the debugger. Connecting multiple sessions to the debugger results in confusion about breakpoint handling. You can verify that the correct browser tab is connected to the debugger by verifying that the Connected indicator in the top right is in view (see the following image). You can have other tabs connected to other areas of API Creator.
Tip:
 At any point, you can clear the debugger state by restarting the debugger. 
For more information:
Follow these steps:
 
  1. In API Creator, with your API open, in the Tools section, click 
    Debugger
    .
    A prompt appears requesting the URL for the debugger. By default, the URL is prefilled. The Debugger runs on port 8181.
  2. Click 
    OK
    .
    The Debugger page displays.
    Stay on the Debugger page throughout your debug session. Consider closing the left navigation bar to get space and to remind you, and then opening more browser tabs to have multiple API Creator views.
The debugger starts in API Creator.
Set Breakpoints
You can set a breakpoint at specific points in your code.
  1. With the debugger started, on the Debugger page in API Creator, select a code type.
  2. Determine where you want to set the breakpoint and click the line number corresponding to the code.
    The line number is encircled in red to indicate a set breakpoint.
When you are stopped at a breakpoint, the server is busy. Other browser tabs (for example, Data Explorer and the REST Lab) are unresponsive until execution resumes.
View your Breakpoints
You can view your breakpoints in the breakpoints table on the 
Breakpoints
 tab. This table displays the list of line numbers and the logic types that are associated to where you have set breakpoints in all the code types.
Clear Breakpoints
You can clear breakpoints from the following tabs in API Creator:
  • On the 
    Breakpoints
     tab, by clicking the trash can for the line number.
  • On the 
    Debugger
     tab, by clicking the line number corresponding to the code.
View the Virtual Machine Properties
You can view a list of the properties and their values that are associated to your virtual machine on the 
VM
 tab.
View the Virtual Machine Threads
You can view a list of the threads in the threads table on the 
Threads
 tab. This table displays the thread identifier and name, the thread state associated to your virtual machine, whether the thread has encountered a breakpoint, and whether a thread is suspended.
Examine Variables
When you are stopped at a breakpoint, you can examine the local variables that you created, and API Creator-supplied variables, such as 
row
. If you have set a breakpoint to a JavaScript library that you have added to your API, when 
CA Live API Creator
 executes that library, the execution stops at that breakpoint. The stops (per JavaScript scoping) show variables from the calling logic.
For more information about JavaScript context variables that are set when 
CA Live API Creator
 invokes JavaScript logic, see Quick Reference Guide.
The following image shows an example of a breakpoint at the 
transformToWebHook
 library in the debugger for the 
B2B Northwind
 API sample:
 
Evaluate Expressions
While stopped at a breakpoint, you can evaluate expressions, such as a function. Evaluating your expressions is useful when you want to see whether a change you are contemplating (for example, a method call) will return the results that you expect.
Your expressions can refer to JavaScript context that 
CA Live API Creator
 passes. For example, you can use the 
row
 and the 
req
 object when you are debugging expressions that are associated with tables or at the resource level and you can use the 
logicContext
 object when you are debugging rules. Your expressions cannot refer to local variables that you declared in your code. Instead, create ad hoc expressions and then evaluate them. You can view these variables on the 
Variables
 tab.
Follow these steps:
 
  1. In API Creator, with your API open, in the Tools section, click 
    Debugger.
     
  2. Click the 
    Evaluate Scope
     tab.
    The Evaluate Scope panel opens. The following image shows an example of the steps:
    eval.png 
  3. Enter code into the eval block.
    Example 1:
     
    function hello() {return "req.getUserProperties().get("argName"): " + req.getUserProperties().get("argName")}
    Example 2:
     
    eval hello()
  4. Click 
    Evaluate
    .
Resume Execution of your JavaScript Code
You can resume execution by clicking 
Step
, and then 
Continue
.
When you first enter a method, you must complete an extra step. This requirement is due to the packaging of your JavaScript code into internal functions and indicates normal operation.
JavaScript Optimization
 
CA 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 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);
The Debugger Limitations
The following are limitations to using the debugger:
  • The debugger does not work properly when you run it on Java SE Development Kit (JDK) 9. Run the debugger using JDK 8.
  • The debugger cannot inspect the 
    virtuals
     variable in resource events.
    For more information about this variable, see Manage Resource Events.