One of the more powerful ways to troubleshoot an issue is the ability to attach a debugger to WebSphere Portal to be able to walk through your code to see where the issue lies.
In this scenario, I am attaching my debugger locally, which means I don't have to be concerned about whether or not the ports are open between my client and the portal machine. If you are using a remote server, you will have to make sure that the port that you're using for debug is open to receive messages on the port.
Enabling debug mode on the server
In order to attach a debugger, you have to have the portal server started in debug mode. There are 2 ways to accomplish this, both of which do the same thing under the covers:
Enable debugMode=true in the server.xml file
- Locate the server.xml file. This will be in the profile directory for the portal server, and then under /config/cells/cellname/nodes/nodename/servers/servername. In my case, the server name is WebSphere_Portal, the cell name is cmknightCell, and the node name is cmknightNode. So the full path for me is /opt/IBM/WebSphere/wp_profile/config/cells/cmknightCell/nodes/cmknightNode/servers/WebSphere_Portal
- Open the server.xml and locate the line that says debugMode="false" (or true if you already have it enabled. Set to true, and also note the value for debugArgs, so you can see which port it will be listening on. In my example, it will be listening on port 7777:
- If you make a change, restart the server.
Enable debug through WebSphere Admin Console
- Login to the WebSphere Admin Console
- Navigate to your server definition (either all servers, or server types depending on your install scenario. Then open the Portal Server:
- From there, navigate to Java and process management > Process Definition:
- Navigate to Additional Properties, Java Virtual Machine:
- On this page, you will see a checkbox for debug mode. I have it enabled already, the default is for the checkbox to be unchecked. Also, you will see the debug args, so you can determine which port to use on the address= flag:
- If you make a change, restart the server.
Attaching the debugger
Now that the server is running debug mode, you have to attach your eclipse/IDE to it. These instructions are for using eclipse or Rational Application Developer, if your'e using an alternate IDE, use the instructions for that IDE. In this example, I have created a custom rendering plugin which I have deployed to my server.
- Open the class you want to debug. In the toolbar, select debug > debug configurations:
- Double click Remote Java Application. This will create a new debug configuration, set up to debug within your project, in the class that you're debugging. Then change the host and port to match the host for portal, and the port that your debug environment
- Click on Debug. Assuming you can connect, eclipse will now be attached to the server. You can check by switching to debug mode in eclipse.
- Click on the list of views, then select Debug:
- After you hit OK, you can check to see if the debugger is attached by switching to the debug view. Once you switch, you should see a set of threads on the server:
Stepping through code
Now that you are attached, we can test stepping through code. For this example, I have a custom rendering plugin that I have deployed to the server. I will reference the plugin in an HTML component, and then render that component to step through the code.
- Create a reference to the plugin tag. I just created HTML component and put the following:
- In the IDE, I have the class for the plugin open. In the render() method of the plugin, I right click on the left side of the class where I want the debug to stop, and then select Toggle Breakpoint. Basically you're setting where the excecution should stop so you can debug:
- Once that's set, now I preview my HTML component. Because my rendering plugin is being used, it will call the render method, and the execution will pause where my debug point is set:
Note that the thread is showing where the execution is stopped, and that within the .java file, you can see which line you are paused on.
- Now, I will step to the next step so that you can see where variable values change. I click on the Step Over button, then I see that I am on the next line. I can see that the variable has been added to the list of variables, and in my case, isDebug is set to false (because the logger is not set to level finest):
I will leave the rest as an exercise for the reader, as the goals will be different based on your needs.
Now you should know how to:
- start portal in debug mode
- attach the eclipse/RAD/IDE debugger to the portal server
- step through your code to determine issues.