Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Application Server Platform Edition 8 Developer's Guide 

Chapter 4
Debugging J2EE Applications

This chapter gives guidelines for debugging applications in Sun Java System Application Server. It includes the following sections:

The domain.xml file described in this chapter is located at domain_dir/config/domain.xml. For more information about this file, see the Sun Java System Application Server Reference.

Enabling Debugging

When you enable debugging, you enable both local and remote debugging. To start the server in debug mode, use the --debug option as follows:

asadmin start-domain --debug [domain_name]

You can then attach to the server from the debugger at its default JPDA port, which is 1044. For example, for UNIX systems:

jdb -attach 1044

For Windows:

jdb -connect com.sun.jdi.SocketAttach:port=1044

You can enable debugging even when the application server is started without the --debug option. This is useful if you start the application server from the Windows Start Menu or if you want to make sure that debugging is always turned on. You can set the server to automatically start up in debug mode in one of these ways:

Sun Java System Application Server debugging is based on the JPDA (Java Platform Debugger Architecture). For more information, see JPDA Options.

Using the Administration Console

To enable debugging for each server restart:

  1. Login to the Administration Console by going to the following URL in your web browser:

    2. http://host:port/asadmin

    For example:

    http://localhost:4848/asadmin

  2. Go to the Application Server page.
  3. Select the JVM Settings tab and the General option.
  4. Check the Debug Enabled box.
  5. To specify a different port (from 1044, the default) to use when attaching the JVM to a debugger, specify address=port_number in the Debug Options field.
  6. If you wish to add JPDA options, add any desired JPDA debugging options in Debug Options. See JPDA Options.
  7. Select the Save button.

Editing the domain.xml File

To enable debugging for each server restart, set the following attributes of the java-config element in the domain.xml file:

For details about the domain.xml file, see the Sun Java System Application Server Reference.

JPDA Options

The default JPDA options in Sun Java System Application Server are as follows:

-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=1044

For Windows, you must change dt_socket to dt_shmem.

If you substitute suspend=y, the JVM starts in suspended mode and stays suspended until a debugger attaches to it. This is helpful if you want to start debugging as soon as the JVM starts.

To specify a different port (from 1044, the default) to use when attaching the JVM to a debugger, specify address=port_number.

You can include additional options. A list of JPDA debugging options is available here:

http://java.sun.com/products/jpda/doc/conninv.html#Invocation

Generating a Stack Trace for Debugging

You can generate a Java stack trace for debugging as described here if the Sun Java System Application Server is in verbose mode (see Enabling Verbose Mode):

http://developer.java.sun.com/developer/technicalArticles/Programming/Stacktrace/

The stack trace goes to the domain_dir/logs/server.log file and also appears on the command prompt screen.

If the -Xrs flag is set (for reduced signal usage) in the domain.xml file (under <jvm-options>), comment it out before generating the stack trace. If the -Xrs flag is used, the server may simply dump core and restart when you send the signal to generate the trace. For more about the domain.xml file, see the Sun Java System Application Server Reference.

The Java Debugger

The Java Debugger (jdb) helps you find and fix bugs in Java language programs. When using the jdb debugger with Sun Java System Application Server, you must attach to the server from the debugger at its default JPDA port, which is 1044. For example, for UNIX systems:

jdb -attach 1044

For Windows:

jdb -connect com.sun.jdi.SocketAttach:port=1044

For more information about the jdb debugger, see the following links:

http://java.sun.com/products/jpda/doc/soljdb.html

http://java.sun.com/products/jpda/doc/conninv.html#JDB

http://java.sun.com/products/jdk/1.2/debugging/JDBTutorial.html

Using the Sun ONE Studio IDE for Debugging

To use the Sun ONE Studio 5 debugger with Sun Java System Application Server:

  1. Start Sun ONE Studio, and mount the directory that contains the application source code you want to debug.
  2. Select the Debug menu and the Attach... option.
  3. Change the Connector:text field to SocketAttach.
  4. Type the host name of the Application Server in the Host text box.
  5. Type the port number you specified when you enabled debugging in the Sun Java System Application Server in the Port text box (the default is 1044), then select OK.

You should be able to debug your Java classes now using Sun ONE Studio.

For help on debugging applications with Sun ONE Studio, select Help, select Contents, then select Debugging Java Programs. You can also consult the Sun ONE Studio documentation.

Using the NetBeans IDE for Debugging

To use the NetBeans 3.5.1 IDE with the Sun Java System Application Server:

  1. Download the latest version of NetBeans from www.netbeans.org.
  2. Set up the classpath in NetBeans to compile J2EE applications using the standard J2EE 1.4 API libraries provided with the Sun Java System Application Server. Perform the following steps in the NetBeans IDE:
    1. In the Menu bar, click on the File menu and select Mount Filesystem.
    2. In the wizard dialog box, select Archive Files as the Filesystem type and click Next.
    3. Navigate the file chooser to the Sun Java System Application Server directory install_dir/lib.
    4. Select j2ee.jar. If you plan to use Sun-specific public APIs provided in the Sun Java System Application Server, you should also select the appserv-ext.jar archive. Click Finish.

      5. The j2ee.jar file should appear in the list of mounted file systems under the Editing pane inside the Filesystems tab of the NetBeans IDE. You can now import J2EE 1.4 API packages in your source files and compile the source files.

  3. Build your application in the NetBeans IDE.
  4. Assemble your application into a J2EE archive file (WAR, JAR, RAR or EAR file) and deploy it to the Sun Java System Application Server.
  5. Start the Sun Java System Application Server with debugging enabled. See Enabling Debugging.
  6. Attach to the Sun Java System Application Server using the Netbeans IDE debugger:
    1. Click on the Debug menu, select Start Session, then select Attach.
    2. In the Attach dialog box, make sure the host (default localhost) and port (default 1044) correspond to the host and JPDA debug port of the Sun Java System Application Server. Click OK.

      3. The Output Window of the Debugger Console should display the message Connection established.

  7. Set break points in your source file in the NetBeans IDE as usual, and run the application.
  8. When finished with debugging, detach from the server by clicking Finish in the Debug menu.

Using the JBuilder IDE for Debugging

To use the JBuilder X Developer or JBuilder X Enterprise debugger with the Sun Java System Application Server:

  1. Start JBuilder X.
  2. If you are using JBuilder X Developer, create a library that holds the J2EE interfaces. This step is not necessary if you are using JBuilder X Enterprise.
    1. Select the Configure Libraries item from the Tools menu. This opens the Configure Libraries dialog box.
    2. Press the New button. This opens the New Library Wizard.
    3. Enter a library name and location.
    4. Press the Add button. This opens a file/directory chooser dialog box.
    5. Navigate through the chooser to select install_dir/lib/j2ee.jar.
    6. If you plan to use Sun-specific public APIs provided with the Sun Java System Application Server, you should also include the install_dir/lib/appserv-ext.jar archive in this library.
    7. Press OK to accept the selection and dismiss the chooser.
    8. Press OK to accept and dismiss the New Library Wizard.
    9. Press OK to accept and dismiss the Configure Libraries dialog box.
  3. Create a project for the application source code.
  4. Add the library created in Step 2 to the project created in Step 3.
    1. Select the Project Properties item from the Project menu. This opens the Project Properties dialog box.
    2. Select the Paths node in the tree on the left side of the dialog box.
    3. Select the Required libraries tab that appears on right side of the dialog box.
    4. Press the Add button. This opens a tree chooser dialog box. The library that was created in Step 2 should appear in the list of libraries.
    5. Select the library created in Step 2.
    6. Press OK to accept the selection and dismiss this dialog box.
    7. Press OK to accept and dismiss the Project Properties dialog box.
  5. Open the project created in Step 3.
  6. Select the Configurations item from the Run menu. This opens the Runtime Configurations dialog box.
  7. Use the New button to create a runtime configuration to be used for debugging your application code. This opens the New Runtime Configuration dialog box.
  8. Give the configuration a unique name.
  9. Expand the Debug node in the tree on the left side of the dialog box.
  10. Select the Remote node.
  11. Set Enable remote debugging to true.
  12. Set the action to Attach.
  13. In the Transport panel, make sure the address (default localhost) and port (default 1044) correspond to the host and JPDA debug port of the Sun Java System Application Server. Select OK.
  14. Assemble your application into a J2EE archive file (WAR, JAR, RAR or EAR file) and deploy it to the Sun Java System Application Server.
  15. Start the Sun Java System Application Server with debugging enabled. See Enabling Debugging.
  16. To use the remote debugging capabilities of the JBuilder X debugger by attaching to the running server process, press Shift+F9.

Sun Java System Message Queue Debugging

Sun Java System Message Queue has a broker logger, which can be useful for debugging JMS, including message-driven bean, applications. You can adjust the logger’s verbosity, and you can send the logger output to the broker’s console using the broker’s -tty option. For more information, see the Sun Java System Message Queue Administrator’s Guide.

Enabling Verbose Mode

If you want to see the server logs and messages printed to System.out or System.err on your command prompt screen, you can start the server in verbose mode. This makes it easy to do simple debugging using print statements, without having to view the server.log file every time.

When the server is in verbose mode, messages are logged to the client in addition to the log file. In addition, pressing Ctrl-C stops the server and pressing Ctrl-\ prints a thread dump. To start the server in verbose mode, use the --verbose option as follows:

asadmin start-domain --verbose [domain_name]

You can enable verbose mode even when the application server is started without the --verbose option. This is useful if you start the application server from the Windows Start Menu or if you want to make sure that verbose mode is always turned on. You can set the server to automatically start up in verbose mode in one of these ways:

Using the Administration Console

To enable verbose mode for each server restart:

  1. Login to the Administration Console by going to the following URL in your web browser:

    2. http://host:port/asadmin

    For example:

    http://localhost:4848/asadmin

  2. Go to the Application Server page.
  3. Select the Logging tab and the General option.
  4. Check the Log Messages to Standard Error box.
  5. Select the Save button.

Editing the domain.xml File

To enable verbose mode for each server restart, set the attributes of the log-service element in the domain.xml file.

You can send exceptions to the client in addition to the log file. Set the following parameter in domain.xml. If the client is a browser, exceptions are displayed in the browser.

<log-service ... log-to-console=true ... />

For details about the domain.xml file, see the Sun Java System Application Server Reference.

Logging

You can use the Sun Java System Application Server’s log files to help debug your applications. For general information about logging, see the Sun Java System Application Server Administration Guide. For information about configuring logging in the domain.xml file, see the Sun Java System Application Server Reference.

Profiling

You can use a profiler to perform remote profiling on the Sun Java System Application Server to discover bottlenecks in server-side performance. This section describes how to configure these profilers for use with Sun Java System Application Server:

The HPROF Profiler

HPROF is a simple profiler agent shipped with the Java 2 SDK. It is a dynamically linked library that interacts with the JVMPI and writes out profiling information either to a file or to a socket in ASCII or binary format.

HPROF can present CPU usage, heap allocation statistics, and monitor contention profiles. In addition, it can also report complete heap dumps and states of all the monitors and threads in the Java virtual machine. For more details on the HPROF profiler, see the JDK documentation at:

http://java.sun.com/products/jpda/doc/soljdb.html

Once HPROF is enabled using the following instructions, its libraries are loaded into the server process. To use HPROF profiling on UNIX, follow these steps:

  1. Configure Sun Java System Application Server in one of these ways:
    • Use the Administration Console:
      1. Login to the Administration Console by going to the following URL in your web browser:

        2.     http://host:port/asadmin

        For example:

            http://localhost:4848/asadmin

      2. Go to the Application Server page.
      3. Select the JVM Settings tab and the Profiler option.
      4. Edit the following fields:
      5. Profiler Name: hprof
      6. Profiler Enabled: true
      7. Classpath: (leave blank)
      8. Native Library Path: (leave blank)
      9. JVM Option: For each of these options, select Add, type the option in the Value field, then check its box:

        -Xrunhprof:file=log.txt,options

      1. Select the Save button.
    • Edit the domain.xml file as appropriate:

      •   <!-- hprof options -->
        <profiler name="hprof" enabled="true">
          <jvm-options>
            -Xrunhprof:file=log.txt,options
          </jvm-options>
        </profiler>

      Note

      Do not use the -Xrs flag.

      Here is an example of options you can use:

      -Xrunhprof:file=log.txt,thread=y,depth=3

      The file option determines where the stack dump is written in Step 2.

      The syntax of HPROF options is as follows:

      -Xrunhprof[:help]|[:option=value,option2=value2, ...]

      Using help lists options that can be passed to HPROF. The output is as follows:

      Hprof usage: -Xrunhprof[:help]|[:<option>=<value>, ...]

      Option Name and Value Description Default
      --------------------- ----------- -------
      heap=dump|sites|all heap profiling all
      cpu=samples|old CPU usage off
      format=a|b ascii or binary output a
      file=<file> write data to file java.hprof
      (.txt for ascii)
      net=<host>:<port> send data over a socket write to file
      depth=<size> stack trace depth 4
      cutoff=<value> output cutoff point 0.0001
      lineno=y|n line number in traces? y
      thread=y|n thread in traces? n
      doe=y|n dump on exit? y

  2. Restart the Application Server. This writes an HPROF stack dump to the file you specified using the file HPROF option in Step 1.

The Optimizeit Profiler

You can purchase Optimizeit™ 4.2 from Intuitive Systems at:

http://www.optimizeit.com/index.html

Once Optimizeit is enabled using the following instructions, its libraries are loaded into the server process. To enable remote profiling with Optimizeit, do one of the following:

  1. Configure your operating system:
    • On Solaris, add Optimizeit_dir/lib to the LD_LIBRARY_PATH environment variable.
    • On Windows, add Optimizeit_dir/lib to the PATH environment variable.
  2. Configure Sun Java System Application Server in one of these ways:
    • Use the Administration Console:
      1. Login to the Administration Console by going to the following URL in your web browser:

        2.     http://host:port/asadmin

        For example:

            http://localhost:4848/asadmin

      2. Go to the Application Server page.
      3. Select the JVM Settings tab and the Profiler option.
      4. Edit the following fields:
      5. Profiler Name: optimizeit
      6. Profiler Enabled: true
      7. Classpath: Optimizeit_dir/lib/optit.jar
      8. Native Library Path: Optimizeit_dir/lib
      9. JVM Option: For each of these options, select Add, type the option in the Value field, then check its box:

        10.     -DOPTITHOME=Optimizeit_dir
            -Xrunpri
            -Xbootclasspath/Optimizeit_dir/lib/oibcp.jar

      10. Select the Save button.
    • Edit the domain.xml file as appropriate:

      • <!-- Optimizeit options -->
      <profiler name="optimizeit" classpath="Optimizeit_dir/lib/optit.jar"
          native-library-path="Optimizeit_dir/lib" enabled="true">
        <jvm-options>-DOPTIT_HOME=Optimizeit_dir</jvm-options>
        <jvm-options>-Xrunpri</jvm-options>
        <jvm-options>-Xbootclasspath/Optimizeit_dir/lib/oibcp.jar</jvm-options>
      </profiler>

  3. In addition, you may have to set the following in your server.policy file. For more information about the server.policy file, see “The server.policy File” on page 60.

    4.   grant codeBase "file:Optimizeit_dir/lib/optit.jar" {
        permission java.security.AllPermission;
      };

  4. Restart the Application Server.

When the server starts up with this configuration, you can attach the profiler. For further details, see the Optimizeit documentation.

Note

If any of the configuration options are missing or incorrect, the profiler may experience problems that affect the performance of the Sun Java System Application Server.



Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.