Debugging WebLogic with an Integrated Debugger

When all else fails, there's really nothing better for tracking down problems inside Java code than an integrated debugger. Just about every commercial and freeware IDE available has some sort of debugging capability. These tools enable you to attach a debugger to a running Java process, and by setting breakpoints at certain places in the code, make it possible for you to step through the execution flow line by line and examine the values of variables along the way.

Preparing the Application for Debugging

Setting up a WebLogic application for debugging is fairly straightforward. The first thing that has to happen is that the Java code must be compiled with debugging information. This inserts source filenames and line numbers into the compiled .class files so that the debugger can step through line by line. This is done by passing in the -g flag to javac on the command line. For example:

javac -g *.java

Alternatively, if you were using Ant for doing builds, you would set the debug attribute of the <javac> task to true. For example:

<javac srcdir="${src}"
    includes="**/*.java"
    destdir="${build}"
    debug="true"/>

After the code has been compiled with debugging information, the next thing to do is to configure WebLogic to accept a connection from a remote debugger. This simply involves adding a few options to the java command line in the startWebLogic shell script.

The command options required for doing remote debugging in Java are fully documented in the J2SE v1.4 documentation, which is available at http://java.sun.com/j2se/1.4.2/docs/guide/jpda/conninv.html. In short, the options needed are -Xdebug (which enables debugging for the VM) and -Xrunjdwp:<sub-options> (which is what the VM uses to communicate with the external debugger). There are too many possible values for <sub-options> to list them all, but here are a few examples of the most common settings:

• -Xrunjdwp:transport=dt_socket,server=y,address=8101 Opens a socket listener on port 8101 that listens for a connection from a remote debugger. The application starts in a suspended state.

• -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8101 Same as the preceding setting, except the application starts in a running state and is not suspended until the remote debugger has been attached and a breakpoint has been reached.

• -Xrunjdwp:transport=dt_socket,server=y,address=8101,onuncaught=y,launch=c:\tools\launchide.bat This delays initialization of the debugging library until an uncaught exception is thrown. When that happens, the VM is suspended and the specified executable is launched to begin debugging the application.

To enable debugging for a WebLogic application, it's necessary to add the appropriate debugging command options to the startup script. For example, if the last line in the startup script %BEA_HOME%\user_projects\mydomain\startWebLogic.cmd looks like this:

"%JAVA_HOME%\bin\java" %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% \
  -Dweblogic.Name=%SERVER_NAME% -Dweblogic.management.username=%WLS_USER% \
  -Dweblogic.management.password=%WLS_PW% \
  -Dweblogic.ProductionModeEnabled=%PRODUCTION_MODE% \
  -Dweblogic.sercurity.policy="%WL_HOME%\server\lib\weblogic.policy" \
  weblogic.Server

we would modify the script as follows to enable debugging:

set DEBUG_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y, suspend=n,address=8101
"%JAVA_HOME%\bin\java" %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% %DEBUG_OPTS% \
  -Dweblogic.Name=%SERVER_NAME% -Dweblogic.management.username=%WLS_USER% \
  -Dweblogic.management.password=%WLS_PW% \
  -Dweblogic.ProductionModeEnabled=%PRODUCTION_MODE% \
  -Dweblogic.sercurity.policy="%WL_HOME%\server\lib\weblogic.policy" \
  weblogic.Server

The last thing to do to be able to debug the application is to configure your IDE for remote debugging. Almost every Java IDE has this capability. In the preceding example, within the debugging properties of the IDE, set remote debugging to true, set the remote connection type to dt_socket, and set the listen address to 8101. To debug, first start WebLogic with the startup script, and then click the Debug button in the IDE. You should then be able to set breakpoints, watch variables, and step through the source code as with any Java application.

Debugging JSPs and EJBs

The described debugging method works very well for the application classes with accessible source code. But sometimes it's necessary or just helpful to be able to step into Java code that has been generated by the container. This is often the case when debugging tag libraries, for example. To see the full tag life cycle, it helps to step into the actual JSP code itself. By default, the container removes the .java files for classes it generates, but this behavior can be overridden.

In the case of JSP files, this property is set within the <jsp-descriptor> element of the weblogic.xml deployment descriptor for the application. To keep the generated .java files, set the keepgenerated property to true, as follows:

<jsp-descriptor>
  <jsp-param>
   <param-name>
     keepgenerated
   </param-name>
   <param-value>
     true
   </param-value>
  </jsp-param>
  ...
</jsp-descriptor>

It's important to note where WebLogic places the generated .java files: They go to the same directory where the generated .class files go. This directory can be specified by the workingDir parameter within the <jsp-descriptor> element of weblogic.xml; otherwise, they go into WEB-INF\classes. This is important because your IDE has to know where the source code for those modules resides, so that it can find the appropriate source for the code it's debugging.

A similar process can be followed for generating source code for the stubs, skeletons, and other supporting classes for EJBs. Although there should not typically be any bugs within the generated classes themselves, it's often helpful to be able to step through those classes to see a more complete picture of the system. When building EJBs, simply specify the -keepgenerated flag to the weblogic.appc tool on the command line. For example:

java weblogic.appc -keepgenerated <other options> ejbApp.jar