|
MyEclipse Remote Debugging Tutorial |
Outline
1. Preface
This document was written using Sun JDK 1.4.2, Eclipse 3.1 and MyEclipse 4.0. All screenshots are based upon the default user interface settings for Eclipse, MyEclipse Enterprise Workbench, and Windows XP. 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.
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:
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.
cd<jboss-home-dir>\\bin<br>setJAVA_OPTS=-Xdebug-Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
.\run.bat
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.
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.
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.
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.
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.
Figure 6 - Example JBoss Configuration
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.
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.