Debugging a protocol plug-in by running the plug-in server in Eclipse

You can debug your protocol plug-in by running the plug-in server in Eclipse.

1. Run the protocol server in Eclipse:
   1. From the Run menu, select External Tools > External Tools Configurations...
   2. Right-click Program and select New
   3. In the Name field, enter ImaPluginServerInEclipse
   4. In the Location field, enter the full path to the Java™ executable file that starts the plug-in server.

      For example, on Windows, your path might look like the following path: C:\eclipse\jdk\jre\bin\java.exe

   5. In the Arguments field, enter the following arguments to run the protocol plug-in server:
      -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n -jar path_to_SDKInstall/ImaTools/ImaPlugin/lib/imaPlugin.jar -i @

      Note:

      • You must enter the correct value for path_to_SDKInstall for your environment.
      • The plug-in server uses port 9091. You must ensure that this port is available before you start the process.
      • The value that is specified for address must match the port value that is specified for the Eclipse remote debugger configuration. This port value is specified in step 2e.
   6. Click Apply
   7. Click Run to start the protocol plug-in server.
2. Start the Eclipse remote Java debugger for the plug-in server that is running in Eclipse:
   1. From the Run menu, select Debug Configurations...
   2. Right-click Remote Java Application and select New
   3. In the Name field, enter ImaPluginOnEclipse
   4. In the Host field, enter the IP address of the host where you are running Eclipse
   5. In the Port field, enter 8000
      Note: This port value must match the value that was specified for the address in the arguments for running the plug-in server in Eclipse. This value was specified in Step 1e.
   6. Select the Source tab and click Add
   7. Select Java Project and click OK
   8. Select the project where the plug-in that you want to debug is and click OK
   9. Click Apply
   10. Click Debug
3. To use the plug-in server that is running in Eclipse to debug your plug-in, you must create a debug version of your plugin.json descriptor file. Set the Classpath property to the location of the compiled classes for the plug-in that you are debugging in Eclipse.

   For example, to debug the sample plug-in that is provided in the SDK bundle, set the Classpath to path_to_SDKInstall/ImaTools/ImaPlugin/samples/jsonmsgPlugin/bin

   Note: If you run Eclipse on Windows, you must either convert the backslashes (\) that are used in the path to forward slashes (/), or use double backslashes (\\).
4. Create a .zip file that contains only the debug plugin.json file in the root directory of the zip.
5. Install the .zip file on your IBM Watson IoT Platform - Message Gateway server. For more information, see Configuring protocol plug-ins.
6. Configure your IBM Watson IoT Platform - Message Gateway server to forward messages to the debug plug-in server that you are running on Eclipse:
   1. Ensure that the PluginDebugPort object is not set by using the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:

      http://<admin-endpoint-IP:Port>/ima/v1/configuration/

      Provide PluginDebugPort object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.

      
      {    
        "PluginDebugPort": 0
      }

   2. Set the PluginDebugServer property to the IP address of the host where Eclipse is running the plug-in server by using the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:

      http://<admin-endpoint-IP:Port>/ima/v1/configuration/

      Provide PluginDebugServer object configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.

      
      {    
        "PluginDebugServer": "string"
      }

      Where:

      PluginDebugServer

      Specifies the IPv4 or IPv6 address of the host where Eclipse is running the plug-in server.

      By default, this value is not set.

      Tip: You can check the value of the PluginDebugServer object by using the IBM Watson IoT Platform - Message Gateway REST API GET method with the following IBM Watson IoT Platform - Message Gateway configuration URI:

      http://<admin-endpoint-IP:Port>/ima/v1/configuration/PluginDebugServer

   3. Stop and restart the server by using the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:

      http://<admin-endpoint-IP:port>/ima/v1/service/restart

      Provide configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.

      
      {    
        "Service": "Server"
      }

7. Set breakpoints in your plug-in source code and debug it by using the client applications for the protocol that is implemented in your plug-in.
8. Optional: If you stop the IBM Watson IoT Platform - Message Gateway server after you start debugging, or if you stop the plug-in server process or the remote Java debugger, you must restart all three processes:
   1. In Eclipse, from the Run menu, select External Tools
   2. Select the ImaPluginServerInEclipse configuration that you created.
   3. From the Run menu, select Debug Configurations..
   4. Find Remote Java Application and select ImaPlugInOnEclipse. Then, click Debug.
   5. On the IBM Watson IoT Platform - Message Gateway server, stop and restart the server by using the IBM Watson IoT Platform - Message Gateway REST API POST method with the following IBM Watson IoT Platform - Message Gateway configuration URI:

      http://<admin-endpoint-IP:port>/ima/v1/service/restart

      Provide configuration data in the payload of the POST method by using the following schema. Content-type is set to application/json. Ensure that capitalization and double quotation marks are used as shown.

      
      {    
        "Service": "Server"
      }