MyEclipse Logo
 

MyEclipse Remote Debugging Tutorial

Outline

download the latest MyEclipse version

help and support
 

1. Preface

This document was written using MyEclipse. All screenshots are based upon the default user interface settings for MyEclipse and Windows XP. However, if you experience difficulty with the instruction of this document, please see the User Feedback section for how to provide feedback to the MyEclipse documentation team.


 

2. 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.

That said, sometimes it is simply not possible or convenient to use the MyEclipse connectors to launch your application server (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

3. Configuring the Server for Remote Debugging

In order to debug your externally launched server with MyEclipse, you'll 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 will describe 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 (click  here).  So, we'll summarize by saying that 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 commandline options needed are shown in Figure 1, below.

Debugging Option
Option Description
-Xdebug Enables 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

Figure 1. JVM debugging options


3.1 WebLogic 8.1 Server

Based on your OS platform, a script called startWLS.cmd or startWLS.sh, is used to start a Weblogic instance from the command line.  The script will read an environment variable called JAVA_OPTIONS and will add 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>\weblogic81\server\bin
setJAVA_OPTIONS=-Xdebug-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
.\startWLS.cmd

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


3.2 Tomcat 5.x Server

Based on your OS platform, a script called catalina.bat or catalina.sh, is used to start a Tomcat 5 instance from the command line.  When started in debug mode the script will read two environment variables, JPDA_TRANSPORT and JPDA_ADDRESS, and add 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

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


3.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 will be read.  Domain.xml contains additional JVM startup options that can be manually set to enable remote debugging.  Editing the domain.xml file as shown in Figure 2, then starting the server with the asadmin command will enable remote debugging.

Sun 8 Config

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


3.4 JBoss 4.0.x Server

Based on your OS platform, a script called run.bat or run.sh, is used to start a JBoss 4.0.x instance from the command line.  The script will read an environment variable called JAVA_OPTS and will add the settings specifed 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

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


4. Deploying to a Remote Server

MyEclipse provides an integrated deployment management facility that can package and deploy 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.  Since this is an advanced tutorial, it is assumed that you are very familiar with the deployment operations detailed in those tutorials.  Please ensure that this is the case before proceeding.

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, as shown in Figure 3.

External Deployment Selection
Figure 3 - Specifying the remote deployment location

Once configured, the remote deployment will behave exactly like a standard deployment, so any exploded deployments will continue to be automatically synchronized with changes in the workspace resources in the project.  Please remember that since you are deploying to a custom location, it is your responsibility to ensure that your application server will load the application from the location you've selected. 

Once your application is deployed and you've configured your server for remote debugging, you may start your server at any time.


5. Debugging a Remote Server

MyEclipse provides a special debug launch configuration, MyEclipse Externally Launched Server, that is designed to attach to remote application servers and support full application debugging.  To create a launch configuration for your external server, click on the Debug Launch Configuration toolbar button, as shown in Figure 4.

Open debug config
Figure 4 - Opening the list of Debug Configurations

Selecting "Debug..." will open the Debug Launch Configuration Management dialog, as shown in Figure 5.  From this dialog, select the MyEclipse configuration then the New button to create a debug launch configuration that can be configured to attach to your application server.

Create Debug Config
Figure 5 - Creating a New MyEclipse Remote Debug Configuration


Figure 6 shows an example remote debugging configuration for JBoss 4, but the settings would be similar for any server.  While the source lookup path will be defaulted appropriately for the project you're debugging, you can also add additional source lookup locations from the 'Source' page of the configuration, as shown in Figure 7.

JBoss Config
Figure 6 - Example JBoss Configuration

JBoss Source Config
Figure 7 - Configuring the Source Lookup Path

Once you configured the new launch configuration, you can either close it for use at a later time or select the 'Debug' option 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 will be shown in the Debug View, as shown in Figure 8.  Please note that the Debug View will not be displayed automatically, so you'll need to either change your perspective to the Debug Perspective, or open the view manually.

JBoss in Debug
Figure 8 - 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.  Basic debugging is covered in depth in the other QuickStarts in the MyEclipse Tutorial library.


6. Summary

This concludes your introduction to Remote Server Debugging using MyEclipse. Additional Tutorial documents are available that introduce working with Web Projects, editing, application server configuration, enterprise application projects and database development. For more information visit the MyEclipse Tutorial library.


7. User Feedback

If you have comments or suggestions regarding this document please submit them to the MyEclipse Documentation Forum.