Part I Development Tasks and Tools

Chapter 1 Setting Up a Development Environment

This chapter gives guidelines for setting up an application development environment in the Sun Java^TM System Application Server. Setting up an environment for creating, assembling, deploying, and debugging your code involves installing the mainstream version of the Application Server and making use of development tools. In addition, sample applications are available. These topics are covered in the following sections:

• Installing and Preparing the Server for Development

• The GlassFish Project

• Development Tools

• Sample Applications

Installing and Preparing the Server for Development

For more information about stand-alone Application Server installation, see the Sun Java System Application Server Platform Edition 9 Installation Guide.

The following components are included in the full installation.

• Application Server core

  • Java EE 5 compliant application server

  • Admin Console

  • asadmin utility

  • Other development and deployment tools

  • Sun Java System Message Queue software

  • Java 2 Platform, Standard Edition (J2SE^TM) 5

  • Java DB database, based on the Derby database from Apache

• JDK

The NetBeans^TM Integrated Development Environment (IDE) bundles the Platform Edition of the Application Server, so information about this IDE is provided as well.

After you have installed Application Server, you can further optimize the server for development in these ways:

• Locate utility classes and libraries so they can be accessed by the proper class loaders. For more information, see Using the System Class Loader or Using the Common Class Loader.

• Set up debugging. For more information, see Chapter 4, Debugging Applications.

• Configure the Java Virtual Machine (JVM^TM) software. For more information, see Chapter 19, Java Virtual Machine and Advanced Settings, in Sun Java System Application Server Platform Edition 9 Administration Guide.

The GlassFish Project

Application Server Platform Edition 9 is developed through the GlassFish^SM project open-source community at https://glassfish.dev.java.net/. The GlassFish project provides a structured process for developing the Application Server platform that makes the new features of Java EE 5 available faster, while maintaining the most important feature of Java EE: compatibility. It enables Java developers to access the Application Server source code and to contribute to the development of the Application Server. The GlassFish project is designed to encourage communication between Sun engineers and the community.

Development Tools

The following general tools are provided with the Application Server:

• The asadmin Command

• The Admin Console

• The asant Utility

• The verifier Tool

The following development tools are provided with the Application Server or downloadable from Sun:

• The NetBeans IDE

• The Migration Tool

The following third-party tools might also be useful:

• Debugging Tools

• Profiling Tools

• The Eclipse IDE

The asadmin Command

The asadmin command allows you to configure a local or remote server and perform both administrative and development tasks at the command line. For general information about asadmin, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

The asadmin command is located in the install-dir/bin directory. Type asadmin help for a list of subcommands.

The Admin Console

The Admin Console lets you configure the server and perform both administrative and development tasks using a web browser. For general information about the Admin Console, click the Help button in the Admin Console. This displays the Application Server online help.

To access the Admin Console, type http://host:4848 in your browser. The host is the name of the machine on which the Application Server is running. By default, the host is localhost. For example:

http://localhost:4848

The asant Utility

Apache Ant 1.6.5 is provided with the Application Server and can be launched from the bin directory using the command asant. The Application Server also provides server-specific tasks for administration and deployment; see Chapter 3, The asant Utility. The sample applications that can be used with the Application Server use Ant build.xml files; see Sample Applications.

For more information about Ant, see the Apache Software Foundation web site at http://ant.apache.org/.

The verifier Tool

The verifier tool checks a Java EE application file, including Java classes and deployment descriptors, for compliance with Java EE specifications. Java EE application files are Java archive (JAR), web archive (WAR), resource adapter archive (RAR), or enterprise archive (EAR) files. Use the verifier tool to check whether an application complies with the Java EE specification and to make applications portable across application servers. The verifier tool can be launched from the command line. For more information, see The verifier Utility in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

The NetBeans IDE

The NetBeans IDE allows you to create, assemble, and debug code from a single, easy-to-use interface. The Platform Edition of the Application Server is bundled with the NetBeans 5.5 IDE. To download the NetBeans IDE, see http://www.netbeans.org. This site also provides documentation on how to use the NetBeans IDE with the bundled Application Server.

You can also use the Application Server with the Sun Java Studio 8 software, which is built on the NetBeans IDE. For more information, see http://developers.sun.com/prodtech/javatools/jsenterprise/.

The Migration Tool

The Migration Tool converts and reassembles Java EE applications and modules developed on other application servers. This tool also generates a report listing how many files are successfully and unsuccessfully migrated, with reasons for migration failure. For more information and to download the Migration Tool, see http://java.sun.com/j2ee/tools/migration/index.html.

For additional information on migration, see the Sun Java System Application Server Platform Edition 9 Upgrade and Migration Guide.

Debugging Tools

You can use several debugging tools with the Application Server. For more information, see Chapter 4, Debugging Applications.

Profiling Tools

You can use several profilers with the Application Server. For more information, see Profiling Tools.

The Eclipse IDE

A plug-in for the Eclipse IDE is available at http://glassfishplugins.dev.java.net/. This site also provides documentation on how to register the Application Server and use Sun-specific deployment descriptors.

Sample Applications

Sample applications that you can examine and deploy to the Application Server are available. If you installed the Application Server as part of installing the Java EE 5 SDK bundle from Java EE 5 Downloads, the samples may already be installed. You can download these samples separately from the Code Samples page if you installed the Application Server without them initially.

Most Application Server samples have the following directory structure:

• The docs directory contains instructions for how to use the sample.

• The build.xml file defines asant targets for the sample. See Chapter 3, The asant Utility.

• The src/java directory under each component contains source code for the sample.

• The src/conf directory under each component contains the deployment descriptors.

With a few exceptions, sample applications follow the standard directory structure described here: http://java.sun.com/blueprints/code/projectconventions.html.

The samples-install-dir/bp-project/main.xml file defines properties common to all sample applications and implements targets needed to compile, assemble, deploy, and undeploy sample applications. In most sample applications, the build.xml file imports main.xml.

In addition to the Java EE 5 sample applications, samples are also available on the GlassFish web site at https://glassfish-samples.dev.java.net/.

Chapter 2 Class Loaders

Understanding Application Server class loaders can help you determine where to place supporting JAR and resource files for your modules and applications. For general information about J2SE class loaders, see Understanding Network Class Loaders.

In a Java Virtual Machine (JVM), the class loaders dynamically load a specific Java class file needed for resolving a dependency. For example, when an instance of java.util.Enumeration needs to be created, one of the class loaders loads the relevant class into the environment. This section includes the following topics:

• The Class Loader Hierarchy

• Using the Java Optional Package Mechanism

• Using the Endorsed Standards Override Mechanism

• Class Loader Universes

• Application-Specific Class Loading

• Circumventing Class Loader Isolation

The Class Loader Hierarchy

Class loaders in the Application Server runtime follow a delegation hierarchy that is illustrated in the following figure and fully described in Table 2–1.

Figure 2–1 Class Loader Runtime Hierarchy

The following table describes the class loaders in the Application Server.

Note that this is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a class loader delegates classloading to its parent before attempting to load a class itself. A class loader parent can be either the System class loader or another custom class loader. If the parent class loader cannot load a class, the class loader attempts to load the class itself. In effect, a class loader is responsible for loading only the classes not available to the parent. Classes loaded by a class loader higher in the hierarchy cannot refer to classes available lower in the hierarchy.

The Java Servlet specification recommends that the Web class loader look in the local class loader before delegating to its parent. You can make the Web class loader follow the delegation inversion model in the Servlet specification by setting delegate="false" in the class-loader element of the sun-web.xml file. It is safe to do this only for a web module that does not interact with any other modules. For details, see class-loader in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

The default value is delegate="true", which causes the Web class loader to delegate in the same manner as the other class loaders. You must use delegate="true" for a web application that accesses EJB components or that acts as a web service client or endpoint. For details about sun-web.xml, see The sun-web.xml File in Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

Using the Java Optional Package Mechanism

Optional packages are packages of Java classes and associated native code that application developers can use to extend the functionality of the core platform.

To use the Java optional package mechanism, copy the JAR files into the domain-dir/lib/ext directory, then restart the server.

For more information, see Optional Packages - An Overview and Understanding Extension Class Loading.

Using the Endorsed Standards Override Mechanism

Endorsed standards handle changes to classes and APIs that are bundled in the JDK but are subject to change by external bodies.

To use the endorsed standards override mechanism, copy the JAR files into the domain-dir/lib/endorsed directory, then restart the server.

For more information and the list of packages that can be overridden, see Endorsed Standards Override Mechanism.

Class Loader Universes

Access to components within applications and modules installed on the server occurs within the context of isolated class loader universes, each of which has its own Application, EJB, Web, and JSP Engine class loaders.

• Application Universe – Each Java EE application has its own class loader universe, which loads the classes in all the modules in the application.

• Individually Deployed Module Universe – Each individually deployed EJB JAR, web WAR, or lifecycle module has its own class loader universe, which loads the classes in the module.

A resource such as a file that is accessed by a servlet, JSP, or EJB component must be in one of the following locations:

• A directory pointed to by the Libraries field or --libraries option used during deployment

• A directory pointed to by the library-directory element in the application.xml deployment descriptor

• A directory pointed to by the class loader’s classpath; for example, the web class loader’s classpath includes these directories:

  module-name/WEB-INF/classes
  module-name/WEB-INF/lib

In iPlanet^TM Application Server 6.x, individually deployed modules shared the same class loader. In subsequent Application Server versions, each individually deployed module has its own class loader universe.

Application-Specific Class Loading

You can specify application-specific library classes during deployment in one of the following ways:

• Use the Admin Console. Open the Applications component, then go to the page for the type of application or module. Type the path in the Libraries field. For details, click the Help button in the Admin Console.

• Use the asadmin deploy command with the --libraries option. For details, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

Application libraries are included in the Application class loader. Paths to libraries can be relative or absolute. A relative path is relative to domain-dir/lib/applibs. If the path is absolute, the path must be accessible to the domain administration server (DAS).

You can use application-specific class loading to specify a different XML parser than the default Application Server XML parser. For details, see http://blogs.sun.com/sivakumart/.

You can also use application-specific class loading to access different versions of a library from different applications.

If multiple applications or modules refer to the same libraries, classes in those libraries are automatically shared. This can reduce the memory footprint and allow sharing of static information. However, applications or modules using application-specific libraries are not portable. Other ways to make libraries available are described in Circumventing Class Loader Isolation.

For general information about deployment, see the Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

If you see an access control error message when you try to use a library, you may need to grant permission to the library in the server.policy file. For more information, see Changing Permissions for an Application.

Circumventing Class Loader Isolation

Since each application or individually deployed module class loader universe is isolated, an application or module cannot load classes from another application or module. This prevents two similarly named classes in different applications from interfering with each other.

To circumvent this limitation for libraries, utility classes, or individually deployed modules accessed by more than one application, you can include the relevant path to the required classes in one of these ways:

• Using the System Class Loader

• Using the Common Class Loader

• Packaging the Client JAR for One Application in Another Application

Using the System class loader or Common class loader requires a server restart and makes a library accessible to any other application or module across the domain.

Using the System Class Loader

To use the System class loader, do one of the following, then restart the server:

• Use the Admin Console. Select the Application Server component, select the JVM Settings tab, select the Path Settings tab, and edit the System Classpath field. For details, click the Help button in the Admin Console.

• Edit the system-classpath attribute of the java-config element in the domain.xml file. For details about domain.xml, see the Sun Java System Application Server Platform Edition 9 Administration Reference.

Using the System class loader makes an application or module accessible to any other application or module across the domain.

Using the Common Class Loader

To use the Common class loader, copy the JAR files into the domain-dir/lib directory or copy the .class files into the domain-dir/lib/classes directory, then restart the server.

Using the Common class loader makes an application or module accessible to any other application or module across the domain.

For example, using the Common class loader is the recommended way of adding JDBC drivers to the Application Server. For a list of the JDBC drivers currently supported by the Application Server, see the Sun Java System Application Server Platform Edition 9 Release Notes. For configurations of supported and other drivers, see Configurations for Specific JDBC Drivers in Sun Java System Application Server Platform Edition 9 Administration Guide.

Packaging the Client JAR for One Application in Another Application

By packaging the client JAR for one application in a second application, you allow an EJB or web component in the second application to call an EJB component in the first (dependent) application, without making either of them accessible to any other application or module.

As an alternative for a production environment, you can have the Common class loader load the client JAR of the dependent application as described in Using the Common Class Loader. Restart the server to make the dependent application accessible across the domain.

To Package the Client JAR for One Application in Another Application

1. Deploy the dependent application.

2. Add the dependent application’s client JAR file to the calling application.

   • For a calling EJB component, add the client JAR file at the same level as the EJB component. Then add a Class-Path entry to the MANIFEST.MF file of the calling EJB component. The Class-Path entry has this syntax:

     Class-Path: filepath1.jar filepath2.jar ...

     Each filepath is relative to the directory or JAR file containing the MANIFEST.MF file. For details, see the Java EE specification.

   • For a calling web component, add the client JAR file under the WEB-INF/lib directory.

3. If you need to package the client JAR with both the EJB and web components, set delegate="true" in the class-loader element of the sun-web.xml file.

   This changes the Web class loader so that it follows the standard class loader delegation model and delegates to its parent before attempting to load a class itself.

   For most applications, packaging the client JAR file with the calling EJB component is sufficient. You do not need to package the client JAR file with both the EJB and web components unless the web component is directly calling the EJB component in the dependent application.

4. Deploy the calling application.

   The calling EJB or web component must specify in its sun-ejb-jar.xml or sun-web.xml file the JNDI name of the EJB component in the dependent application. Using an ejb-link mapping does not work when the EJB component being called resides in another application.

   You do not need to restart the server.

Chapter 3 The asant Utility

Apache Ant 1.6.5 is provided with Application Server and can be launched from the bin directory using the command asant. The Application Server also provides server-specific tasks, which are described in this section.

Make sure you have done these things before using asant:

1. Include install-dir/bin in the PATH environment variable (/usr/sfw/bin for Sun Java Enterprise System on Solaris). The Ant script provided with the Application Server, asant, is located in this directory. For details on how to use asant, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

2. If you are executing platform-specific applications, such as the exec or cvs task, the ANT_HOME environment variable must be set to the Ant installation directory.

   • The ANT_HOME environment variable for Sun Java Enterprise System must include the following paths.

     • /usr/sfw/bin – the Ant binaries (shell scripts)

     • /usr/sfw/doc/ant – HTML documentation

     • /usr/sfw/lib/ant – Java classes that implement Ant

   • The ANT_HOME environment variable for all other platforms is install-dir/lib.

3. Set up your password file. The argument for the passwordfile option of each Ant task is a file. This file contains the password in the following format.

   AS_ADMIN_PASSWORD=password
   

   For more information about password files, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

This section covers the following asant-related topics:

• Application Server asant Tasks

• Reusable Subelements

For more information about Ant, see the Apache Software Foundation web site at http://ant.apache.org/.

For information about standard Ant tasks, see the Ant documentation at http://ant.apache.org/manual/.

Application Server asant Tasks

Use the asant tasks provided by the Application Server for assembling, deploying, and undeploying modules and applications, and for configuring the server. The tasks are as follows:

• The sun-appserv-deploy Task

• The sun-appserv-undeploy Task

• The sun-appserv-component Task

• The sun-appserv-admin Task

• The sun-appserv-jspc Task

• The sun-appserv-update Task

The sun-appserv-deploy Task

Deploys any of the following.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

Subelements of sun-appserv-deploy

The following table describes subelements for the sun-appserv-deploy task. These are objects upon which this task acts.

Attributes of sun-appserv-deploy

The following table describes attributes for the sun-appserv-deploy task.

Examples of sun-appserv-deploy

Here is a simple application deployment script with many implied attributes:

<sun-appserv-deploy
file="${assemble}/simpleapp.ear"
passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-deploy
 file="${assemble}/simpleapp.ear"
 name="simpleapp"
 force="true"
 precompilejsp="false"
 verify="false"
 upload="true"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example deploys multiple components to the same Application Server running on a remote server:

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
		 asinstalldir="/opt/sun" >
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"
	 contextroot="test"/>
 <component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

This example deploys the same components as the previous example because the three components match the fileset criteria, but note that it is not possible to set some component-specific attributes. All component-specific attributes (name and contextroot) use their default values.

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
		 asinstalldir="/opt/sun" >
 <fileset dir="${assemble}" includes="**/*.?ar" />
</sun-appserv-deploy>

The sun-appserv-undeploy Task

Undeploys any of the following.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

Subelements of sun-appserv-undeploy

The following table describes subelements for the sun-appserv-undeploy task. These are objects upon which this task acts.

Attributes of sun-appserv-undeploy

The following table describes attributes for the sun-appserv-undeploy task.

Examples of sun-appserv-undeploy

Here is a simple application undeployment script with many implied attributes:

<sun-appserv-undeploy name="simpleapp" passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-undeploy
 name="simpleapp"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example demonstrates using the archive files (EAR and WAR, in this case) for the undeployment, using the component name (for undeploying the EJB component in this example), and undeploying multiple components.

<sun-appserv-undeploy passwordfile="${passwordfile}">
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-undeploy>

The sun-appserv-component Task

Enables or disables the following Java EE component types that have been deployed to the Application Server.

• Enterprise application (EAR file)

• Web application (WAR file)

• Enterprise Java Bean (EJB-JAR file)

• Enterprise connector (RAR file)

• Application client

You do not need to specify the archive to enable or disable a component: only the component name is required. You can use the component archive, however, because it implies the component name.

Subelements of sun-appserv-component

The following table describes subelements for the sun-appserv-component task. These are objects upon which this task acts.

Attributes of sun-appserv-component

The following table describes attributes for the sun-appserv-component task.

Examples of sun-appserv-component

Here is a simple example of disabling a component:

<sun-appserv-component
 action="disable"
 name="simpleapp"
 passwordfile="${passwordfile}" />

Here is a simple example of enabling a component:

<sun-appserv-component
 action="enable"
 name="simpleapp"
 passwordfile="${passwordfile}" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-component
 action="enable"
 name="simpleapp"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 asinstalldir="${asinstalldir}" />

This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and using the component name (for an EJB component in this example).

<sun-appserv-component action="disable" passwordfile="${passwordfile}">
 <component file="${assemble}/simpleapp.ear"/>
 <component file="${assemble}/simpleservlet.war"/>
 <component name="simplebean" />
</sun-appserv-component>

The sun-appserv-admin Task

Enables arbitrary administrative commands and scripts to be executed on the Application Server. This is useful for cases where a specific Ant task has not been developed or a set of related commands are in a single script.

Attributes of sun-appserv-admin

The following table describes attributes for the sun-appserv-admin task.

Examples of sun-appserv-admin

Here is an example of executing the create-jms-dest command:

<sun-appserv-admin command="create-jms-dest --desttype topic">

Here is an example of using explicitcommand to execute the create-jms-dest command:

<sun-appserv-admin command="create-jms-dest --user adminuser --host localhost 
--port 4848 --desttype topic --target server1 simpleJmsDest">

The sun-appserv-jspc Task

Precompiles JSP source code into Application Server compatible Java code for initial invocation by Application Server. Use this task to speed up access to JSP files or to check the syntax of JSP source code. You can feed the resulting Java code to the javac task to generate class files for the JSP files.

Attributes of sun-appserv-jspc

The following table describes attributes for the sun-appserv-jspc task.

Example of sun-appserv-jspc

The following example uses the webapp attribute to generate Java source files from JSP files. The sun-appserv-jspc task is immediately followed by a javac task, which compiles the generated Java files into class files. The classpath value in the javac task must be all on one line with no spaces.

<sun-appserv-jspc
 destdir="${assemble.war}/generated"
 webapp="${assemble.war}"
 classpath="${assemble.war}/WEB-INF/classes"
 asinstalldir="${asinstalldir}" />
<javac
 srcdir="${assemble.war}/WEB-INF/generated"
 destdir="${assemble.war}/WEB-INF/generated"
 debug="on"
 classpath="${assemble.war}/WEB-INF/classes:${asinstalldir}/lib/
   appserv-rt.jar:${asinstalldir}/lib/appserv-ext.jar">
 <include name="**/*.java"/>
</javac>

The sun-appserv-update Task

Enables deployed applications (EAR files) and modules (EJB JAR, RAR, and WAR files) to be updated and reloaded for fast iterative development. This task copies modified class files, XML files, and other contents of the archive files to the appropriate subdirectory of the domain-dir/applications directory, then touches the .reload file to cause dynamic reloading to occur.

This is a local task and must be executed on the same machine as the Application Server.

For more information about dynamic reloading, see the Sun Java System Application Server Platform Edition 9 Application Deployment Guide.

Attributes of sun-appserv-update

The following table describes attributes for the sun-appserv-update task.

Example of sun-appserv-update

The following example updates the Java EE application foo.ear, which is deployed to the default domain, domain1.

<sun-appserv-update file="foo.ear"/>

Reusable Subelements

Reusable subelements of the Ant tasks for the Application Server are as follows. These are objects upon which the Ant tasks act.

• The component Subelement

• The fileset Subelement

The component Subelement

Specifies a Java EE component. Allows a single task to act on multiple components. The component attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.

Attributes of component

The following table describes attributes for the component element.

Examples of component

You can deploy multiple components using a single task. This example deploys each component to the same Application Server running on a remote server.

<sun-appserv-deploy passwordfile="${passwordfile}" host="greg.sun.com"
	 asinstalldir="/opt/s1as8" >
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"
	 contextroot="test"/>
<component file="${assemble}/simplebean.jar"/>
</sun-appserv-deploy>

You can also undeploy multiple components using a single task. This example demonstrates using the archive files (EAR and WAR, in this case) and the component name (for the EJB component).

<sun-appserv-undeploy passwordfile="${passwordfile}">
<component file="${assemble}/simpleapp.ear"/
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-undeploy>

You can enable or disable multiple components. This example demonstrates disabling multiple components using the archive files (EAR and WAR, in this case) and the component name (for the EJB component).

<sun-appserv-component action="disable" passwordfile="${passwordfile}">
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-component>

The fileset Subelement

Selects component files that match specified parameters. When fileset is included as a subelement, the name and contextroot attributes of the containing element must use their default values for each file in the fileset. For more information, see http://ant.apache.org/manual/CoreTypes/fileset.html.

Chapter 4 Debugging Applications

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

• Enabling Debugging

• JPDA Options

• Generating a Stack Trace for Debugging

• Sun Java System Message Queue Debugging

• Enabling Verbose Mode

• Application Server Logging

• Profiling Tools

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 --user adminuser --debug [domain-name]

You can then attach to the server from the Java Debugger (jdb) at its default Java Platform Debugger Architecture (JPDA) port, which is 9009. For example, for UNIX® systems:

jdb -attach 9009

For Windows:

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

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

• Java Platform Debugger Architecture - The Java Debugger: http://java.sun.com/products/jpda/doc/soljdb.html

• Java Platform Debugger Architecture - Connecting with JDB: http://java.sun.com/products/jpda/doc/conninv.html#JDB

Application Server debugging is based on the JPDA. For more information, see JPDA Options.

You can attach to the Application Server using any JPDA compliant debugger, including that of NetBeans, Sun Java Studio, JBuilder, Eclipse, and so on.

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.

To Set the Server to Automatically Start Up in Debug Mode

1. Select the Application Server component and the JVM Settings tab in the Admin Console.

2. Check the Debug Enabled box.

3. To specify a different port (from 9009, the default) to use when attaching the JVM to a debugger, specify address= port-number in the Debug Options field.

4. To add JPDA options, add any desired JPDA debugging options in Debug Options. See JPDA Options.

See Also

For details, click the Help button in the Admin Console from the JVM Settings page.

JPDA Options

The default JPDA options in Application Server are as follows:

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

For Windows, you can 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 9009, 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 at http://java.sun.com/products/jpda/doc/conninv.html#Invocation.

Generating a Stack Trace for Debugging

To generate a Java stack trace for debugging, use the asadmin generate-jvm-report --type=thread command. The stack trace goes to the domain-dir/logs/server.log file and also appears on the command prompt screen. For more information about the asadmin generate-jvm-report command, see the Sun Java System Application Server Platform Edition 9 Reference Manual.

Sun Java System Message Queue Debugging

Sun Java System Message Queue has a broker logger, which can be useful for debugging Java Message Service (JMS) applications, 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 3.7 UR1 Administration Guide.

Enabling Verbose Mode

To have the server logs and messages printed to System.out 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.

To start the server in verbose mode, use the --verbose option as follows:

asadmin start-domain --user adminuser --verbose [domain-name]

On Windows platforms, you must perform an extra preparation step if you want to use Ctrl-Break to print a thread dump. In the install-dir/asenv.bat file, change AS_NATIVE_LAUNCHER="false" to AS_NATIVE_LAUNCHER="true".

When the server is in verbose mode, messages are logged to the console or terminal window in addition to the log file. In addition, pressing Ctrl-C stops the server and pressing Ctrl-\ (on UNIX platforms) or Ctrl-Break (on Windows platforms) prints a thread dump. On UNIX platforms, you can also print a thread dump using the jstack command (see http://java.sun.com/j2se/1.5.0/docs/tooldocs/share/jstack.html) or the command kill -QUIT process_id.

Application Server Logging

You can use the Application Server’s log files to help debug your applications. In the Admin Console, select the Application Server component, then click the View Log Files button in the General Information page. To change logging settings, select the Logging tab. For details about logging, click the Help button in the Admin Console.

Profiling Tools

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

• The NetBeans Profiler

• The HPROF Profiler

• The Optimizeit Profiler

• The Wily Introscope Profiler

• The JProbe Profiler

Information about comprehensive monitoring and management support in the Java^TM 2 Platform, Standard Edition (J2SE^TM platform) is available at http://java.sun.com/j2se/1.5.0/docs/guide/management/index.html.

The NetBeans Profiler

For information on how to use the NetBeans profiler, see http://www.netbeans.org and http://blogs.sun.com/roller/page/bhavani?entry=analyzing_the_performance_of_java.

The HPROF Profiler

The Heap and CPU Profiling Agent (HPROF) is a simple profiler agent shipped with the Java 2 SDK. It is a dynamically linked library that interacts with the Java Virtual Machine Profiler Interface (JVMPI) and writes out profiling information either to a file or to a socket in ASCII or binary format.

HPROF can monitor CPU usage, heap allocation statistics, and 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/j2se/1.5.0/docs/guide/jvmpi/jvmpi.html#hprof.

After HPROF is enabled using the following instructions, its libraries are loaded into the server process.

To Use HPROF Profiling on UNIX

1. Using the Admin Console, select the Application Server component, the JVM Settings tab, and the Profiler tab.

2. Edit the following fields:

   • Profiler Name – hprof

   • Profiler Enabled – true

   • Classpath – (leave blank)

   • Native Library Path – (leave blank)

   • JVM Option – Select Add, type the HPROF JVM option in the Value field, then check its box. The syntax of the HPROF JVM option is as follows:

     -Xrunhprof[:help]|[:param=value,param2=value2, ...]

     Here is an example of params you can use:

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

     The file parameter determines where the stack dump is written.

     Using help lists parameters 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

     ---

     Note –

     Do not use help in the JVM Option field. This parameter prints text to the standard output and then exits.

     The help output refers to the parameters as options, but they are not the same thing as JVM options.

     ---

3. Restart the Application Server.

   This writes an HPROF stack dump to the file you specified using the file HPROF parameter.

The Optimizeit Profiler

You can purchase Optimizeit from Borland at http://www.borland.com/optimizeit.

After Optimizeit is enabled using the following instructions, its libraries are loaded into the server process.

To Enable Remote Profiling With Optimizeit

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 the Application Server using the Admin Console:

   1. Select the Application Server component, the JVM Settings tab, and the Profiler tab.

   2. Edit the following fields:

      • Profiler Name – optimizeit

      • Profiler Enabled – true

      • Classpath – Optimizeit-dir/lib/optit.jar

      • Native Library Path – Optimizeit-dir/lib

      • JVM Option – For each of these options, select Add, type the option in the Value field, then check its box

        -DOPTITHOME=Optimizeit-dir -Xrunpri:startAudit=t -Xbootclasspath/p:/Optimizeit-dir/lib/oibcp.jar

3. In addition, you might have to set the following in your server.policy file.

   For more information about the server.policy file, see The server.policy File.

   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.

See Also

For further details, see the Optimizeit documentation.

Troubleshooting

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

The Wily Introscope Profiler

Information about Introscope® from Wily Technology is available at http://www.wilytech.com/solutions/products/Introscope.html.

After Introscope is installed using the following instructions, its libraries are loaded into the server process.

To Enable Remote Profiling With Introscope

1. Using the Admin Console, select the Application Server component, the JVM Settings tab, and the Profiler tab.

2. Edit the following fields before clicking Save:

   • Name – wily

   • Enabled – true

   • Classpath – Wily-dir/ProbeBuilder.jar:Wily-dir/Agent.jar

   • Native Library Path – (leave blank)

   • JVM Option – (leave blank)

   When the server starts up with this configuration, you can attach the profiler.

See Also

For further details, see the Introscope documentation.

Troubleshooting

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

The JProbe Profiler

Information about JProbe^TM from Sitraka is available at http://www.quest.com/jprobe/.

After JProbe is installed using the following instructions, its libraries are loaded into the server process.

To Enable Remote Profiling With JProbe

1. Install JProbe 3.0.1.1.

   For details, see the JProbe documentation.

2. Configure Application Server using the Admin Console:

   1. Select the Application Server component, the JVM Settings tab, and the Profiler tab.

   2. Edit the following fields before selecting Save and restarting the server:

      • Profiler Name – jprobe

      • Profiler Enabled – true

      • Classpath – (leave blank)

      • Native Library Path – JProbe-dir/profiler

      • JVM Option – For each of these options, select Add, type the option in the Value field, then check its box

        -Xbootclasspath/p:JProbe-dir/profiler/jpagent.jar

        -Xrunjprobeagent

        -Xnoclassgc

      ---

      Note –

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

      ---

      When the server starts up with this configuration, you can attach the profiler.

3. Set the following environment variable:

   JPROBE_ARGS_0=-jp_input=JPL-file-path

   See Step 6 for instructions on how to create the JPL file.

4. Start the server instance.

5. Launch the jpprofiler and attach to Remote Session. The default port is 4444.

6. Create the JPL file using the JProbe Launch Pad. Here are the required settings:

   1. Select Server Side for the type of application.

   2. On the Program tab, provide the following details:

      • Target Server – other-server

      • Server home Directory – install-dir

      • Server class File – com.sun.enterprise.server.J2EERunner

      • Working Directory – install-dir

      • Classpath – install-dir/lib/appserv-rt.jar

      • Source File Path – source-code-dir (in case you want to get the line level details)

      • Server class arguments – (optional)

      • Main Package – com.sun.enterprise.server

      You must also set VM, Attach, and Coverage tabs appropriately. For further details, see the JProbe documentation. After you have created the JPL file, use this an input to JPROBE_ARGS_0.