test

Sun GlassFish Enterprise Server v3 Prelude Developer's Guide

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 GlassFishTM Enterprise Server. Setting up an environment for creating, assembling, deploying, and debugging your code involves installing the mainstream version of the Enterprise 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

For more information about stand-alone Enterprise Server installation, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

The following components are included in the full installation.

The NetBeansTM Integrated Development Environment (IDE) bundles the GlassFish edition of the Enterprise Server, so information about this IDE is provided as well.

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

The GlassFish Project

Enterprise Server v3 Prelude is developed through the GlassFish project open-source community at https://glassfish.dev.java.net/. The GlassFish project provides a structured process for developing the Enterprise 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 Enterprise Server source code and to contribute to the development of the Enterprise 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 Enterprise Server:

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

The following third-party tools might also be useful:

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 GlassFish Enterprise Server v3 Prelude Reference Manual.

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

The Administration Console

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

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


http://localhost:4848

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.

The NetBeans IDE

The NetBeans IDE allows you to create, assemble, and debug code from a single, easy-to-use interface. The GlassFish edition of the Enterprise Server is bundled with the NetBeans 6.1 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 Enterprise Server.

You can also use the Enterprise 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 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 Enterprise Server and use Sun-specific deployment descriptors.

Debugging Tools

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

Profiling Tools

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

Chapter 2 Class Loaders

Understanding Enterprise 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 JVM implementation, 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:

Note –

For GlassFish v3 Prelude, EJB modules are not supported unless the optional EJB container add-on component is downloaded from the Update Tool. Web services are not supported unless the optional Metro (JSR 109) add-on component is downloaded from the Update Tool. For information about the Update Tool, see the Sun GlassFish Enterprise Server v3 Prelude Installation Guide.

The Class Loader Hierarchy

Class loaders in the Enterprise Server runtime follow a delegation hierarchy that is fully described in Table 2–1.

Table 2–1 Sun GlassFish Enterprise Server Class Loaders

Class Loader 

Description 

Bootstrap

The Bootstrap class loader loads the basic runtime classes provided by the JVM software. 

Extension

The Extension class loader loads classes from JAR files present in the system extensions directory, domain-dir/lib/ext. It is parent to the Public API class loader. See Using the Java Optional Package Mechanism.

Public API

The Public API class loader makes available all classes specifically exported by the Enterprise Server runtime for use by deployed applications. This includes, but is not limited to, Java EE APIs and other Sun GlassFish APIs. It is parent to the Common class loader. 

Common

The Common class loader loads JAR files in the as-install/lib directory, then classes in the domain-dir/lib/classes directory, followed by JAR files in the domain-dir/lib directory. Using domain-dir/lib/classes or domain-dir/lib is recommended whenever possible, and required for custom login modules and realms. It is parent to the Connector class loader. See Using the Common Class Loader.

Connector

The Connector class loader is a single class loader instance that loads individually deployed connector modules, which are shared across all applications. It is parent to the Applib class loader. 

Applib

The Applib class loader loads the library classes, specified during deployment, for a specific enabled module; see Application-Specific Class Loading. One instance of this class loader is present in each class loader universe; see Class Loader Universes. It is parent to the Archive class loader.

When multiple deployed applications use the same library, they share the same instance of the library. One library cannot reference classes from another library. 

Archive

The Archive class loader loads classes from the WAR and JAR files or directories (for directory deployment) of modules deployed to the Enterprise Server. This class loader also loads any application-specific classes generated by the Enterprise Server runtime, such as stub classes or servlets generated by JSP pages. 

Delegation

Note that the class loader hierarchy is not a Java inheritance hierarchy, but a delegation hierarchy. In the delegation design, a class loader delegates class loading to its parent before attempting to load a class itself. 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.

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 modules installed on the server occurs within the context of isolated class loader universes, each of which has its own Applib and Archive class loaders.

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

Application-Specific Class Loading

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

Application libraries are included in the Applib 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).

If multiple 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, modules using application-specific libraries are not portable. Other ways to make libraries available are described in Circumventing Class Loader Isolation.

One library cannot reference classes from another library.

For general information about deployment, see the Sun GlassFish Enterprise Server v3 Prelude Application Deployment Guide.

Note –

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 module class loader universe is isolated, a module cannot load classes from another module. This prevents two similarly named classes in different modules from interfering with each other.

To circumvent this limitation for libraries, utility classes, or individually deployed modules, you can include the relevant path to the required classes. See Using the Common Class Loader.

Using the Common Class Loader

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

Using the Common class loader makes a module accessible to all modules deployed on servers that share the same configuration.

For example, using the Common class loader is the recommended way of adding JDBC drivers to the Enterprise Server. For a list of the JDBC drivers currently supported by the Enterprise Server, see the Sun GlassFish Enterprise Server v3 Prelude Release Notes. For configurations of supported and other drivers, see Configuration Specifics for JDBC Drivers in Sun GlassFish Enterprise Server v3 Prelude Administration Guide.

To activate custom login modules and realms, place the JAR files in the domain-dir/lib directory or the class files in the domain-dir/lib/classes directory, then restart the server.

Chapter 3 Debugging Applications

This chapter gives guidelines for debugging applications in the Sun GlassFish Enterprise Server. It includes the following sections:

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:

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

You can attach to the Enterprise 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.

ProcedureTo Set the Server to Automatically Start Up in Debug Mode

  1. Use the Administration Console. Select the Enterprise Server component and the JVM Settings tab.

  2. Check the Debug Enabled box.

  3. To specify a different port (from 9009, the default) to use when attaching the JVM software 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 Administration Console from the JVM Settings page.

JPDA Options

The default JPDA options in Enterprise 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 software 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 software starts.

To specify a different port (from 9009, the default) to use when attaching the JVM software 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 GlassFish Enterprise Server v3 Prelude Reference Manual.

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]

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/javase/6/docs/technotes/tools/share/jstack.html) or the command kill -QUIT process_id.

Profiling Tools

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

Information about comprehensive monitoring and management support in the JavaTM 2 Platform, Standard Edition (J2SETM platform) is available at http://java.sun.com/javase/6/docs/technotes/guides/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 technical article at http://java.sun.com/developer/technicalArticles/Programming/HPROF.html.

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

ProcedureTo Use HPROF Profiling on UNIX

  1. Use the Administration Console. Select the Enterprise Server component and the JVM Settings tab. Then select 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 Enterprise Server.

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

The JProbe Profiler

Information about JProbeTM 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.

ProcedureTo Enable Remote Profiling With JProbe

  1. Install JProbe 3.0.1.1.

    For details, see the JProbe documentation.

  2. Configure Enterprise Server using the Administration Console:

    1. Select the Enterprise Server component and the JVM Settings tab. Then select 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 Enterprise 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.

  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 – as-install

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

      • Working Directory – as-install

      • Classpath – as-install/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.