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:
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.
Enterprise Server core
Java Platform, Standard Edition (Java SE) 6
Java EE 6 compliant application server
Other development and deployment tools
Java DB database, based on the Derby database from Apache
The NetBeansTM Integrated Development Environment (IDE) bundles the GlassFish edition of the Enterprise Server, so information about this IDE is provided as well.
Locate utility classes and libraries so they can be accessed by the proper class loaders. For more information, see Using the Common Class Loader.
Set up debugging. For more information, see Chapter 3, Debugging Applications.
Configure the Virtual Machine for the JavaTM platform (JVMTM software). For more information, see Chapter 4, Administering the Virtual Machine for the Java Platform, in Sun GlassFish Enterprise Server v3 Prelude Administration Guide.
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.
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 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 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:
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 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/.
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.
You can use several debugging tools with the Enterprise Server. For more information, see Chapter 3, Debugging Applications.
You can use several profilers with the Enterprise Server. For more information, see Profiling Tools.
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:
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.
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
The Bootstrap class loader loads the basic runtime classes provided by the JVM software.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Individually Deployed Module Universe – Each individually deployed EJB JAR or web WAR 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 module’s classpath; for example, a web module’s classpath includes these directories:
You can specify module-specific library classes during deployment in one of the following ways:
Use the Administration Console. Open the Applications component, then go to the page for the type of module. Select the Deploy button. Type the comma-separated paths in the Libraries field. For details, click the Help button in the Administration Console.
Use the asadmin deploy command with the --libraries option and specify comma-separated paths. For details, see the Sun GlassFish Enterprise Server v3 Prelude Reference Manual.
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.
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.
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.
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.
This chapter gives guidelines for debugging applications in the Sun GlassFish Enterprise Server. It includes the following sections:
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]
jdb -attach 9009
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
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.
Use the Administration Console. Select the Enterprise Server component and the JVM Settings tab.
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.
To add JPDA options, add any desired JPDA debugging options in Debug Options. See JPDA Options.
For details, click the Help button in the Administration Console from the JVM Settings page.
The default JPDA options in Enterprise Server are as follows:
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.
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.
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.
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.
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 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.
Edit the following fields:
Profiler Name – hprof
Profiler Enabled – true
Classpath – (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:
Here is an example of params you can use:
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
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.
Restart the Enterprise Server.
This writes an HPROF stack dump to the file you specified using the file HPROF parameter.
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.
Install JProbe 126.96.36.199.
For details, see the JProbe documentation.
Select the Enterprise Server component and the JVM Settings tab. Then select the Profiler tab.
Edit the following fields before selecting Save and restarting the server:
Profiler Name – jprobe
Profiler Enabled – true
Classpath – (leave blank)
JVM Option – For each of these options, select Add, type the option in the Value field, then check its box
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.
Set the following environment variable:
See Step 6 for instructions on how to create the JPL file.
Start the server.
Launch the jpprofiler and attach to Remote Session. The default port is 4444.
Create the JPL file using the JProbe Launch Pad. Here are the required settings:
Select Server Side for the type of application.
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.