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