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.

Download and extract the contents of the SDK bundle. Then, follow the instructions in ImaTools/ImaPlugin/README.txt to import the sample plug-in projects that are provided with the SDK bundle.

If you run the protocol plug-in server in Eclipse, you can run the protocol plug-in server process remotely and use the Eclipse Amlen server to forward messages to the external plug-in server process. This approach is intended for use during the early stages of development. With this approach, you can deploy a plug-in .zip file that contains only a plugin.json descriptor file and no JAR files. Then, you can debug and update your plug-in classes in your local development environment without redeploying a plug-in .zip file on the server. When you use this method of debugging, you must use a non-standard version of the plugin.json file. This version of the file provides the class path for your plug-in classes in your development environment.

In later stages of development, you must test your production protocol plug-in by installing it and running it on your Eclipse Amlen server. For more information, see Debugging a protocol plug-in by running the plug-in server and the plug-in on the Eclipse Amlen server.

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.
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
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 (\\).
Create a .zip file that contains only the debug plugin.json file in the root directory of the zip.
Install the .zip file on your Eclipse Amlen server. For more information, see Configuring protocol plug-ins.
Configure your Eclipse Amlen 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 Eclipse Amlen REST API POST method with the following Eclipse Amlen 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 Eclipse Amlen REST API POST method with the following Eclipse Amlen 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 Eclipse Amlen REST API GET method with the following Eclipse Amlen configuration URI:
  http://<admin-endpoint-IP:Port>/ima/v1/configuration/PluginDebugServer
3. Stop and restart the server by using the Eclipse Amlen REST API POST method with the following Eclipse Amlen 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"
}
```
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.
Optional: If you stop the Eclipse Amlen 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 Eclipse Amlen server, stop and restart the server by using the Eclipse Amlen REST API POST method with the following Eclipse Amlen 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"
}
```

When you complete this phase of debugging, reset the PluginDebugServer object on the Eclipse Amlen server. Use the Eclipse Amlen REST API POST method with the following Eclipse Amlen 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": ""
}
```
Move to the next phase of debugging, by running the plug-in server and your plug-in on an Eclipse Amlen server. For more information, see Debugging a protocol plug-in by running the plug-in server and the plug-in on the Eclipse Amlen server.