How to configure remote JSP debugging
under WebSphere Application Servers
Introduction
This article describes how you can create a run and debug configuration in IntelliJ IDEA 5.1 (or higher) to allow your Web modules with JSP files to be remotely debugged under WebSphere 5.1 and WebSphere 6.0 application servers. It also describes how to configure these application servers to enable integration with IntelliJ IDEA, and provides you with step-by-step instructions for application deployment.
Requirements
Before making any settings, make sure that the following requirements are met:
- WebSphere 5.1 or 6.0 application server is installed (full or express version). IntelliJ IDEA does not have any bundled servers, so you need to install them yourself.
- JDK (Sun Java2TM Standard Edition SDK) 1.4 or less is installed. Although IntelliJ IDEA supports JDK 5.0, WebSphere application servers require JDK 1.4 or less.
- WebSphere application server is started.
You can find the full documentation on how to install, start, and initially configure the server at http://www-306.ibm.com/software/websphere/.
Configuring WebSphere Application Server
To enable remote debugging on the server, perform the following steps:
- Start the server's Administrative Console.
- Expand Servers > Application Servers.
Note:
- Click the server name and clic the Configuration tab
- Navigate to the Additional Properties group and click the Debugging Service link.
- Make sure that the debugging service is enabled at server startup.
- Click the Apply button. Then save the settings (for example, using the notification message)
Note:
- Restart the server using WebSphere's or operating system's administration tools.
Generating the Application Archive File
IntelliJ IDEA can generate the WAR, EAR, or JAR file for your application automatically. For this purpose, you need to configure your module (Web, J2EE Application, or EJB).
- In IntelliJ IDEA, click File > Settings (Ctrl + Alt + S), and then select Modules.
- In the Modules list, click the module for which you need to generate the archive file.
- Click the J2EE Build Settings tab.
- Select the Create web module war/ear/jar file check box, and specify the location of the file. This path will be required later, on the application deployment stage.
Apply the changes, and make the project (click the Build > Make Project menu or press Ctrl + F9).
The application is now ready for deployment.
Deploying Application
You deploy the application using the WebSphere application server's tools.
- Start the server's Administrative Console.
- Click Applications > Install New Application, and then click your server.
- Select Local file system or Remote file system depending on your server installation, and then specify the path to your WAR, EAR, or JAR file (usually, it corresponds to the path you specified when generating the application archive file in IntelliJ IDEA).
- In the Context Root text box, specify the context (e.g. "myContext").
Note:
- Click Next. Skip the next screen and click Next again. Note:
- On the first step of the Install New Application wizard, select the Enable class reloading check box, and then click Next. This allows you to redeploy the application without reinstalling it
Note:
- On the second step, select the check box next to your Web module to map it to the server. Then click Next.
- On the third step, select the check box next to your Web module to map the virtual host to it, and then click Next.
- On the last step, just click Finish. The deployment will start. Note:
- When the deployment is finished, the server console will show you the installation results page. Save the configuration, for example using the Save to Master Configuration link on this page.
- Click Applications > Enterprise Applications. In the list of applications your application should be displayed with the �Stopped� status (red cross icon).
- Select the check box next to your application, and then click Start.
Note:
Creating Run/Debug Configuration
WebSphere 5.1/6.0 application servers are supported by means of the general IntelliJ IDEA integration with the JSR compatible servers and do not have a server-specific type of Run/Debug configuration. You need to create a configuration for a JSR45 compatible server and then modify it according to WebSphere application server's needs.
- In IntelliJ IDEA, click the Run > Edit Configurations menu, and then click the JSR45 Compatible Server tab.
- Click the plus sign or press Insert to add a new configuration, and then click Remote. Specify some configuration name.
- Click the Configure button to add an application server.
- In the Application Servers dialog box, click Add, and then specify some server name.
- Click the Attach Classes button, and find the j2ee.jar file for your version of WebSphere Application server (<installation folder>\lib\j2ee.jar).
Note:
- In the Application Servers dialog box, click Apply to save the changes, and then in the configuration, in the Application Server list, select the added server.
- In the Startup page text box, specify the home page of your web application in the following format:
- WebSphere Application Server 5.1
http://localhost:7080/<ContextRoot>/<home page>
- WebSphere Application Server 6.0
http://localhost:9080/<ContextRoot>/<home page>
"7080" and "9080" are default ports for the WebSphere 5.1 and 6.0 servers, respectively. If you have changed the default port, specify the actual port number instead.
<ContextRoot> is name of web context used during application deployment, e.g. "myContext".
<home page> can be any page from your Web module.
- Optionally, you can configure the application server log to display its content in the IntelliJ IDEA's Run tool window, in the console.
Click the Add button, and then in the Edit Log Files Aliases dialog specify some alias name (e.g. "activity"). In the Log File Location text box, specify the location of the activity.log file. By default, this file is located in the <home>\logs folder.
- In the JSP package text box, enter one of the following:
- WebSphere Application Server 5.1
org.apache.jsp
- WebSphere Application Server 6.0
com.ibm._jsp
- In the VM options variable text box, type DEBUG.
- If you use WebSphere Application Server 5.1, select to use the specific JSP's line mapping model. For the WebSphere Application Server 6.0 this check box is ignored, but it is recommended to clear it.
- In the Port text box, specify the port number of the corresponding application server (it should be the same as specified for the startup page).
Note:
- Click the Startup/Connection tab, and then click Debug. Check that the Socket option is selected, and the Port number is 7777.
Debugging Application
To start debugging the application in IntelliJ IDEA, just click Run > Debug or press Shift + F9. You can use all the power of the IntelliJ IDEA debugger for the JSP files running on the WebSphere Application Server, including breakpoints, stepping commands, watches, etc.
Note:
Troubleshooting
The server crashes during the debug session
Such problems may appear if you use the IBM's virtual machine supplied with the WebSphere server. Possible solutions in this case are:
- Run IntelliJ IDEA with the command line option:
-Didea.debugger.keep.temp.objects=false
In this case IntelliJ IDEA will avoid calling certain methods from debug API.
- Use Sun's JDK 1.4 or less
IntelliJ IDEA is unable to open the debugger port
In most cases, it is an internal WebSphere server error. Try to restart the WebSphere application server.
Conclusion
We hope that this article helped you to configure remote debugging successfully. If you have encountered any problems that are not described in the Troubleshooting section, don't hesitate to contact our technical support: support@jetbrains.com.