Debugging a Custom Adapter

Debug a custom Java adapter (that was built using the adapter toolkit) by starting it in debug mode and using an Integrated Development Environment (IDE) that supports remote debugging, such as Eclipse.

Prerequisites
Task

The steps below describe how to debug a custom or an example adapter using an Eclipse IDE. You can use similar steps to debug a custom adapter using another IDE that supports remote debugging.

  1. Choose an example adapter from %ESP_HOME%\adapters\framework\examples or another adapter of your choice.
  2. Compile the transporter and formatter module Java files to .class files (debug version) and compress them to .jar files using the jar.exe tool.
  3. Copy these debug files to the %ESP_HOME%\adapters\framework\libj directory.
  4. Back up the modulesdefine.xml file in the $ESP_HOME/adapters/framework/config directory.
  5. (Perform only if debugging an example adapter) Prepare the adapter configuration file:
    1. Copy the $ESP_HOME/adapters/framework/examples/modulesdefine.xml file to the $ESP_HOME/adapters/framework/config.
    2. Edit the set_example_env.bat or set_example_env.sh files and the adapter configuration file for the example adapter. Specify values for the username and password elements in the example adapter configuration file.
  6. Start the ESP cluster node:
    Windows
    cd %ESP_HOME%\cluster\nodes\<nodename>
    %ESP_HOME%\bin\esp_server --cluster-node <nodename>.xml
    or
    UNIX
    cd $ESP_HOME/cluster/nodes/<nodename>
    $ESP_HOME/bin/esp_server --cluster-node <nodename>.xml
  7. Deploy the ESP project on the cluster:
    Windows
    %ESP_HOME%\bin\esp_cluster_admin" --uri=esp://localhost:19011
    --username=sybase --password=sybase --add_project --workspacename=
    <workspacename> --project-name=<projectname> --ccx=<modelname>.ccx
    or
    UNIX
    $ESP_HOME/bin/esp_cluster_admin" --uri=esp://localhost:19011
    --username=sybase --password=sybase --add_project --workspacename=
    <workspacename> --project-name=<projectname> --ccx=<modelname>.ccx
  8. Start the deployed project on the cluster:
    Windows
    %ESP_HOME%\bin\esp_cluster_admin" --uri=esp://localhost:19011
    --username=sybase --password=sybase --start_project --
    workspace-name=<workspacename> --project-name=<projectname>
    or
    UNIX
    $ESP_HOME/bin/esp_cluster_admin" --uri=esp://localhost:19011
    --username=sybase --password=sybase --start_project --
    workspace-name=<workspacename> --project-name=<projectname>
  9. Modify the start.bat or start.sh script file in the %ESP_HOME%\adapters\framework\bin directory to set the suspend debug parameter to y.
    For example,
    set DEBUG_PARA=-Xdebug
            -Xrunjdwp:transport=dt_socket,address=8998,server=y,suspend=y
  10. Start the adapter in debug mode:
    Windows
    %ESP_HOME%\adapters\framework\bin\start.bat
    <ADAPTER_EXAMPLE_CONFIG_FILE> –debug
    or
    $ESP_HOME/adapters/framework/bin/start.sh
    <ADAPTER_EXAMPLE_CONFIG_FILE> –debug
    where <ADAPTER_EXAMPLE_CONFIG_FILE> specifies the full path to the configuration file of the adapter you are debugging.
  11. Launch Eclipse.
  12. Select Run > Debug Configurations.
  13. On the left-hand side of the Debug Configurations window, select Remote Java Application, then right-click and select New to create a connection to the adapter you wish to debug.
  14. On the right-hand side of the Debug Configuration window, select the Connect tab:
    1. Specify the name of your adapter in the Name field.
    2. Use the Browse... button to select the ESP project to which your adapter is connected.
    3. Select Standard (Socket Attach) from the drop down menu for Connection Type.
    4. Specify localhost for the Host connection property.
    5. Specify 8998 for the Port connection property.
    6. Click Apply.
  15. Select Run > Toggle Breakpoint to create a breakpoint at a specific line.
    Set all breakpoints before advancing to the next step.
  16. Click Debug.
Related concepts
Formatter Modules
Transporter Modules
EspConnector Modules
Related tasks
Accessing Adapter Toolkit API Reference Information
Create a Custom Adapter