facebook

MyEclipse Remote Debugging Tutorial


1. Introduction

This is an advanced Tutorial that discusses configuring and debugging applications running in application servers that are not launched using a MyEclipse server connector, either on the machine running MyEclipse or on a different machine. For general ease of configuration and debugging, it is highly recommended that the MyEclipse server connectors be used for all server operations as detailed in the Application Server Tutorial. Please read it first before proceeding with this tutorial.

Sometimes it is simply not possible or convenient to use the MyEclipse connectors to launch your application server. For example, you might need to debug a remote instance of the server in an integration or production environment. Or, your server startup scripts might be highly modified or dictated as part of your development process, so you are simply not allowed to change your external server management practices. Finally, MyEclipse simply might not directly support the particular server you need to debug. If these or similar cases apply to you, then this tutorial will show you how to do the following:

    • Configure your server for remote debugging
    • Deploy your application to the server
    • Use a custom Eclipse launch configuration to communicate with your server
    • Debug your Java code in all servers
    • Debug JSPs in JSR-045 compliant servers


2. Configuring the Server for Remote Debugging

To debug your externally launched server with MyEclipse, you need to deploy your application, and then start the server in a manner that enables it to be controlled by an external debugger through JPDA. This section describes the basics of configuring any application server for remote debugging while providing concrete instructions for a few example servers. 

To configure a Java application, including servers, for remote debugging, several additional Java virtual machine options must be specified. Full documentation on all the remote debugging options, along with definitions and examples, is available directly from Sun. In summary, the virtual machine must be told to launch in debug mode and listen to a particular port for a debugger to connect. An example of the command line options needed are shown below.

Debugging OptionOption Description
-XdebugEnables debugging
-Xrunjdwp:
transport=dt_socket,
 address=8000,
 server=y,
 suspend=n
Run the JDWP debugger with these options:
Use a socket for communication
Listen on port 8000 for the debugger to connect
Listen for a debugger application to attach
Don’t wait for the debugger to connect before proceeding with startup


2.1 WebLogic Server

Based on your OS platform, a script called start WebLogic.cmd or startWebLogic.sh, is used to start a Weblogic instance from the command line. The script reads an environment variable called JAVA_OPTIONS and adds the settings specifed to the arguments used to start WebLogic when the script is invoked. On Windows, this can be done by opening a cmd.exe shell, and issuing the following commands:

cd <bea-home-dir><weblogic-version>serverbin
setJAVA_OPTIONS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
.startWebLogic.cmd

Substitute <bea-home-dir> in the above path with the actual location of your BEA home folder. Other versions of WebLogic can be started in a similar manner. After the server has fully started, it can then be connected to and controlled by MyEclipse, as described in Section 3.


2.2 Tomcat Server

Based on your OS platform, a script called catalina.bat or catalina.sh, is used to start a Tomcat instance from the command line. When started in debug mode, the script reads two environment variables, JPDA_TRANSPORT and JPDA_ADDRESS, and adds the settings specifed to the arguments used to start Tomcat. On Windows, this can be done by opening a cmd.exe shell, and issuing the following commands:

cd <tomcat-home-dir>bin
set JPDA_TRANSPORT=dt_socket
set JPDA_ADDRESS=8000
catalina.bat jpda start

Substitute <tomcat-home-dir> in the above path with the actual location of your Tomcat installation folder. Other versions of Tomcat can be started in a similar manner. After the server has fully started, it can then be connected to and controlled by MyEclipse, as described in Section 3.


2.3 Sun Java System Application Server Edition 8.x

Based on your OS platform, a script called asadmin.bat or asadmin.sh, is used to start a Sun Java System Application Server Edition 8 instance from the command line. When your server domain is started, its configuration file, called domain.xml is read. Domain.xml contains additional JVM startup options that can be set manually to enable remote debugging. Editing the domain.xml file as shown below, and then starting the server with the as admin command enables remote debugging.

Sun 8 Config
Edits to domain.xml that allow for remote debugging

After the server has fully started, it can then be connected to and controlled by MyEclipse, as described in Section 3.


2.4 JBoss Server

Based on your OS platform, a script called run.bat or run.sh, is used to start a JBoss instance from the command line. The script reads an environment variable called JAVA_OPTS, and adds the settings specified to the arguments used to start JBoss when the script is invoked. On Windows, this can be done by opening a cmd.exe shell, and issuing the following commands:

cd<jboss-home-dir>bin<br>setJAVA_OPTS=-Xdebug-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
.run.bat

Substitute <jboss-home-dir> in the above path with the actual location of your JBoss installation folder. Other versions of JBoss can be started in a similar manner. After the server has fully started, it can then be connected to and controlled by MyEclipse, as described in Section 3.


3. Deploying to a Remote Server

MyEclipse provides an integrated deployment management facility that packages and deploys your application to any file system accessible from your development system, including remote mounts and shares. Application deployment basics are described in the Web Development, and Enterprise Development quickstarts. Because this is an advanced tutorial, it is assumed that you are very familiar with the deployment operations detailed in those tutorials.

When deploying to a standard, MyEclipse-launched application server, the deployment location is automatically set by MyEclipse based on the server type and method of deployment selected. For a remote server, there is an “<Externally Launched>” server type that allows complete specification of the deployment location.

External Deployment Selection
Specifying the remote deployment location

After configuration, the remote deployment behaves exactly like a standard deployment, so exploded deployments continue to be automatically synchronized with changes in the project resources. Remember that because you are deploying to a custom location, it is your responsibility to ensure that your application server loads the application from the location you’ve selected.

After your application is deployed and you’ve configured your server for remote debugging, you can start your server at any time.


4. Debugging a Remote Server

MyEclipse provides a special debug launch configuration, MyEclipse Externally Launched Server, designed to attach to remote application servers and support full application debugging. To create a launch configuration for your external server, click the drop-down arrow on the Debug icon on the toolbar, and select Debug Configurations from the menu.

The Debug Configurations window opens. Select MyEclipse Externally Launched Server, and click the New Launch Configuration icon to create a debug launch configuration for attaching to your application server.

Create Debug Config
Creating a new remote debug configuration

The image below shows an example remote debugging configuration for JBoss 4, but the settings would be similar for any server.

JBoss Config
Example JBoss configuration

While the source lookup path is defaulted appropriately for the project you’re debugging, you can add additional source lookup locations from the Source page of the configuration.

JBoss Source Config
Configuring the source lookup path

After you configure the new launch configuration, you can either close it for use at a later time or click the Debug button if your remote server is already running and listening for debug connections. After the application server has been started externally and the debug configuration is launched, a new debug process is shown in the Debug view. 

Note: The Debug view does not display automatically; therefore you need to either change to the Debug perspective, or open the view manually.

JBoss in Debug
External server attached to debugger

At this point, debugging your application is the same as it would be if you used one of the built-in MyEclipse server connectors to launch the server locally. See the Debugger Learning Center for more details about debugging applications.