Sun GlassFish Enterprise Server v2.1.1 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 JavaTM System 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 the Sun Java Enterprise System, Enterprise Server installation is part of the system installation process. For more information, see http://www.sun.com/software/javaenterprisesystem/index.html.

For more information about stand-alone Enterprise Server installation, see the Sun GlassFish Enterprise Server v2.1.1 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 v2.1.1 is developed through the GlassFishTM 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 Java ES edition of the Enterprise Server is based on the GlassFish source code, but provides additional value-added features such as access to a high-availability database (HADB) for session persistence and failover.

Usage Profiles

When you install a domain, the usage profile you select determines the features that are available by default. Here is a summary of the usage profiles:

For more information about usage profiles, see Usage Profiles in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.

High Availability Features

High availability features such as load balancing and session failover are discussed in detail in the Sun GlassFish Enterprise Server v2.1.1 High Availability Administration Guide. This book describes the following features in the following sections:

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 v2.1.1 Reference Manual.

The asadmin command is located in the as-install/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 Enterprise Server online help.

To access the Admin Console, type http://host:4848 (developer profile) or https://host:4848 (cluster and enterprise profiles) 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 asant Utility

Apache Ant 1.6.5 is provided with the Enterprise Server and can be launched from the bin directory using the command asant. The Enterprise 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 Enterprise 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 GlassFish Enterprise Server v2.1.1 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 GlassFish edition of the Enterprise 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 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 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.

Debugging Tools

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

Profiling Tools

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

Sample Applications

Sample applications that you can examine and deploy to the Enterprise Server are available. If you installed the Enterprise 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 Enterprise Server without them initially.

Most Enterprise Server samples have the following directory structure:

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 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 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

Class loaders in the Enterprise 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

Figure shows the class loader runtime hierarchy.

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

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, plus any classes from JAR files present in the system extensions directory. It is parent to the System class loader. To add JAR files to the system extensions, directory, see Using the Java Optional Package Mechanism.

System

The System class loader loads Enterprise Server launch classes. It is parent to the Shared Chain class loader. It is created based on the system-classpath attribute of the java-config element in the domain.xml file. In the developer profile, select the Enterprise Server component in the Admin Console and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration. Then select the Path Settings tab and edit the System Classpath field. See Using the System Class Loader and java-config in Sun GlassFish Enterprise Server v2.1.1 Administration Reference.

Add the classes to the system-classpath attribute of the domain administration server (DAS) in addition to the system-classpath attribute on the server instances that use the classes. The default name for the DAS configuration is server-config.

Shared Chain 

The Shared Chain class loader loads most of the core Enterprise Server classes. It is parent to the MBean class loader and the Common class loader. Classes specified by the classpath-prefix and classpath-suffix attributes of the java-config element in the domain.xml file are added to this class loader. In the developer profile, select the Enterprise Server component in the Admin Console and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration. Then select the Path Settings tab and edit the Classpath Prefix or Classpath Suffix field.

The environment classpath is included if env-classpath-ignored="false" is set in the java-config element.

Use classpath-prefix to place libraries ahead of Enterprise Server implementation classes in the shared chain. The classpath-prefix is ideal for placing development and diagnostic patches. To avoid overriding implementation classes, use classpath-suffix to place libraries after implementation classes in the shared chain.

Add the classes to the classpath-prefix or classpath-suffix attribute of the DAS in addition to the corresponding attribute on the server instances that use the classes. The default name for the DAS configuration is server-config.

MBean

The MBean class loader loads the MBean implementation classes. See MBean Class Loading.

Common

The Common class loader loads classes in the domain-dir/lib/classes directory, followed by JAR files in the domain-dir/lib directory. It is parent to the Connector class loader. No special classpath settings are required. The existence of these directories is optional; if they do not exist, the Common class loader is not created. 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 LifeCycleModule class loader and the Application class loader. 

LifeCycleModule

The LifeCycleModule class loader is created once per lifecycle module. Each lifecycle-module element’s classpath attribute is used to construct its own class loader. For more information on lifecycle modules, see Chapter 13, Developing Lifecycle Listeners.

Application

The Application class loader loads the classes in a specific enabled individually deployed module or Java EE application. One instance of this class loader is present in each class loader universe; see Class Loader Universes. The Application class loader is created with a list of URLs that point to the locations of the classes it needs to load. It is parent to the Web class loader.

The Application class loader loads classes in the following order: 

  1. Classes specified by the library-directory element in the application.xml deployment descriptor or the –-libraries option during deployment; see Application-Specific Class Loading

  2. Classes specified by the application's or module's location attribute in the domain.xml file, determined during deployment

  3. Classes in the classpaths of the application's sub-modules

  4. Classes in the application's or module's stubs directory

The location attribute points to domain-dir/applications/j2ee-apps/app-name or domain-dir/applications/j2ee-modules/module-name.

The stubs directory is domain-dir/generated/ejb/j2ee-apps/app-name or domain-dir/generated/ejb/j2ee-modules/module-name.

Web

The Web class loader loads the servlets and other classes in a specific enabled web module or a Java EE application that contains a web module. This class loader is present in each class loader universe that contains a web module; see Class Loader Universes. One instance is created for each web module. The Web class loader is created with a list of URLs that point to the locations of the classes it needs to load. The classes it loads are in WEB-INF/classes or WEB-INF/lib/*.jar. It is parent to the JSP Engine class loader.

JSP Engine

The JSP Engine class loader loads compiled JSP classes of enabled JSP files. This class loader is present in each class loader universe that contains a JSP page; see Class Loader Universes. The JSP Engine class loader is created with a list of URLs that point to the locations of the classes it needs to load.

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 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 GlassFish Enterprise Server v2.1.1 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 Sun GlassFish Enterprise Server v2.1.1 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.

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 application-specific library classes during deployment in one of the following ways:

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). The Enterprise Server automatically synchronizes these libraries to all remote cluster instances when the cluster is restarted. However, libraries specified by absolute paths are not guaranteed to be synchronized.


Tip –

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

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 GlassFish Enterprise Server v2.1.1 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 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 or Common class loader requires a server restart and makes a library accessible to all applications or modules deployed on servers that share the same configuration.

Using the System Class Loader

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

Using the System class loader makes an application or module accessible to all applications or modules deployed on servers that share the same configuration.

Add the classes to the system-classpath attribute of the DAS in addition to the system-classpath attribute on the server instances that use the classes. The default name for the DAS configuration is server-config.

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 all applications or 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 v2.1.1 Release Notes. For configurations of supported and other drivers, see Configurations for Specific JDBC Drivers in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.

Sharing Libraries Across a Cluster

To share libraries across a specific cluster, copy the JAR files to the domain-dir/config/cluster-config-name/lib directory. Then add the path to the JAR files to the System class loader as explained in Using the System Class Loader or to the Shared Chain class loader as explained in Table 2–1.


Note –

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile or the enterprise profile. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server v2.1.1 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 to all applications or modules deployed on servers that share the same configuration.

ProcedureTo 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 Enterprise Server and can be launched from the bin directory using the command asant. The Enterprise Server also provides server-specific tasks, which are described in this section.

Make sure you have done these things before using asant:

  1. Include as-install/bin in the PATH environment variable (/usr/sfw/bin for Sun JavaTM Enterprise System, or Java ES, on Solaris). The Ant script provided with the Enterprise Server, asant, is located in this directory. For details on how to use asant, see the Sun GlassFish Enterprise Server v2.1.1 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 Java ES on Solaris is /usr/sfw and 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 as-install/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 GlassFish Enterprise Server v2.1.1 Reference Manual.

This section covers the following asant-related topics:

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/.


Note –

Variables in the examples in this chapter, such as ${asinstalldir}, reference values defined in build.xml or properties files.


Enterprise Server asant Tasks

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

The sun-appserv-deploy Task

Deploys any of the following to a local or remote Enterprise Server instance.

Subelements of sun-appserv-deploy

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

Table 3–1 The sun-appserv-deploy Subelements

Element 

Description 

The server Subelement

An Enterprise Server instance 

The component Subelement

A component to be deployed 

The fileset Subelement

A set of component files that match specified parameters 

Attributes of sun-appserv-deploy

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

Table 3–2 The sun-appserv-deploy Attributes

Attribute 

Default 

Description 

file

none 

(optional if a component or fileset subelement is present, otherwise required) The component to deploy. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. If upload is set to false, this must be an absolute path on the server machine.

name

file name without extension 

(optional) The display name for the component being deployed. 

force

true

(optional) If true, the component is overwritten if it already exists on the server. If false, sun-appserv-deploy fails if the component exists.

retrievestubs

client stubs not saved 

(optional) The directory where client stubs are saved. This attribute is inherited by nested component elements.

precompilejsp

false

(optional) If true, all JSP files found in an enterprise application (.ear) or web application (.war) are precompiled. This attribute is ignored for other component types. This attribute is inherited by nested component elements.

verify

false

(optional) If true, syntax and semantics for all deployment descriptors are automatically verified for correctness. This attribute is inherited by nested component elements.

contextroot

file name without extension 

(optional) The context root for a web module (WAR file). This attribute is ignored if the component is not a WAR file. 

dbvendorname

sun-ejb-jar.xml entry

(optional) The name of the database vendor for which tables can be created. Allowed values are javadb, db2, mssql, oracle, postgresql, pointbase, derby (also for CloudScape), and sybase, case-insensitive.

If not specified, the value of the database-vendor-name attribute in sun-ejb-jar.xml is used.

If no value is specified, a connection is made to the resource specified by the jndi-name subelement of the cmp-resource element in the sun-ejb-jar.xml file, and the database vendor name is read. If the connection cannot be established, or if the value is not recognized, SQL-92 compliance is presumed.

For details, see Generation Options for CMP.

createtables

sun-ejb-jar.xml entry

(optional) If true, causes database tables to be created for beans that need them. If false, does not create tables. If not specified, the value of the create-tables-at-deploy attribute in sun-ejb-jar.xml is used.

For details, see Generation Options and Generation Options for CMP.

dropandcreatetables

sun-ejb-jar.xml entry

(optional) If true, and if tables were automatically created when this application was last deployed, tables from the earlier deployment are dropped and fresh ones are created.

If true, and if tables were not automatically created when this application was last deployed, no attempt is made to drop any tables. If tables with the same names as those that would have been automatically created are found, the deployment proceeds, but a warning indicates that tables could not be created.

If false, settings of create-tables-at-deploy or drop-tables-at-undeploy in the sun-ejb-jar.xml file are overridden.

For details, see Generation Options and Generation Options for CMP.

uniquetablenames

sun-ejb-jar.xml entry

(optional) If true, specifies that table names are unique within each application server domain. If not specified, the value of the use-unique-table-names property in sun-ejb-jar.xml is used.

For details, see Generation Options for CMP.

enabled

true

(optional) If true, enables the component.

deploymentplan

none 

(optional) A deployment plan is a JAR file containing Sun-specific descriptors. Use this attribute when deploying an EAR file that lacks Sun-specific descriptors. 

availabilityenabled

false

(optional) If true, enables high availability features, including persistence of HTTP sessions and checkpointing of the stateful session bean state.

generatermistubs

false

(optional) If true, generates the static RMI-IIOP stubs and puts them in the client JAR file.

upload

true

(optional) If true, the component is transferred to the server for deployment. If the component is being deployed on the local machine, set upload to false to reduce deployment time. If a directory is specified for deployment, upload must be false.

virtualservers

default virtual server only 

(optional) A comma-separated list of virtual servers to be deployment targets. This attribute applies only to application (.ear) or web (.war) components and is ignored for other component types. This attribute is inherited by nested server elements.

user

admin

(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements.

host

localhost

(optional) Target server. When deploying to a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.

port

4848

(optional) The administration port on the target server. This attribute is inherited by nested server elements.

target

name of default instance 

(optional) Target application server instance. This attribute is inherited by nested server elements.

asinstalldir

see description 

(optional) The installation directory for the local Enterprise Server installation, which is used to find the administrative classes. If not specified, the command checks if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

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"
 target="${default-instance-name}"
 asinstalldir="${asinstalldir}" />

This example deploys multiple components to the same Enterprise Server instance 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 multiple components to two Enterprise Server instances running on remote servers. In this example, both servers are using the same admin password. If this were not the case, each password could be specified in the server element.

<sun-appserv-deploy passwordfile="${passwordfile}" asinstalldir="/opt/sun" >
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
 <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 from a local or remote Enterprise Server instance.

Subelements of sun-appserv-undeploy

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

Table 3–3 The sun-appserv-undeploy Subelements

Element 

Description 

The server Subelement

An Enterprise Server instance 

The component Subelement

A component to be deployed 

The fileset Subelement

A set of component files that match specified parameters 

Attributes of sun-appserv-undeploy

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

Table 3–4 The sun-appserv-undeploy Attributes

Attribute 

Default 

Description 

name

file name without extension 

(optional if a component or fileset subelement is present or the file attribute is specified, otherwise required) The display name for the component being undeployed.

file

none 

(optional) The component to undeploy. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. 

droptables

sun-ejb-jar.xml entry

(optional) If true, causes database tables that were automatically created when the bean(s) were last deployed to be dropped when the bean(s) are undeployed. If false, does not drop tables.

If not specified, the value of the drop-tables-at-undeploy attribute in sun-ejb-jar.xml is used.

For details, see Generation Options and Generation Options for CMP.

cascade

false

(optional) If true, deletes all connection pools and connector resources associated with the resource adapter being undeployed.

If false, undeployment fails if any pools or resources are still associated with the resource adapter.

This attribute is applicable to connectors (resource adapters) and applications with connector modules. 

user

admin

(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements.

host

localhost

(optional) Target server. When deploying to a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.

port

4848

(optional) The administration port on the target server. This attribute is inherited by nested server elements.

target

name of default instance 

(optional) Target application server instance. This attribute is inherited by nested server elements.

asinstalldir

see description 

(optional) The installation directory for the local Enterprise Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

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"
 target="${default-instance-name}"
 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>

As with the deployment process, components can be undeployed from multiple servers in a single command. This example shows the same three components being removed from two different instances of the Enterprise Server. In this example, the passwords for both instances are the same.

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

The sun-appserv-instance Task

Starts, stops, restarts, creates, or removes one or more application server instances.


Note –

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile or the enterprise profile. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.


Subelements of sun-appserv-instance

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

Table 3–5 The sun-appserv-instance Subelements

Element 

Description 

The server Subelement

An Enterprise Server instance 

Attributes of sun-appserv-instance

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

Table 3–6 The sun-appserv-instance Attributes

Attribute 

Default 

Description 

action

none 

The control command for the target application server. Valid values are start, stop, create, and delete. A restart sends the stop command followed by the start command. The restart command is not supported on Windows.

debug

false

(optional) Deprecated. If action is set to start, specifies whether the server starts in debug mode. This attribute is ignored for other values of action. If true, the instance generates additional debugging output throughout its lifetime. This attribute is inherited by nested server elements.

nodeagent

none 

(required if action is create, otherwise ignored) The name of the node agent on which the instance is being created.

cluster

none 

(optional, applicable only if action is create) The clustered instance to be created. The server’s configuration is inherited from the named cluster.

The config and cluster attributes are mutually exclusive. If both are omitted, a stand-alone server instance is created.

config

none 

(optional, applicable only if action is create) The configuration for the new stand-alone instance.

The configuration must exist and must not be default-config (the cluster configuration template) or an already referenced stand-alone configuration (including the administration server configuration server-config).

The config and cluster attributes are mutually exclusive. If both are omitted, a stand-alone server instance is created.

property

none 

(optional, applicable only if action is create) Defines system properties for the server instance. These properties override port settings in the server instance’s configuration. The following properties are defined: http-listener-1-port, http-listener-2-port, orb-listener-1-port, SSL-port, SSL_MUTUALAUTH-port, JMX_SYSTEM_CONNECTOR_port.

System properties can be changed after instance creation using the system property commands. For details, see the Sun GlassFish Enterprise Server v2.1.1 Reference Manual.

user

admin

(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements.

host

localhost

(optional) Target server. If it is a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.

port

4848

(optional) The administration port on the target server. This attribute is inherited by nested server elements.

instance

name of default instance 

(optional) Target application server instance. This attribute is inherited by nested server elements.

asinstalldir

see description 

(optional) The installation directory for the local Enterprise Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

Examples of sun-appserv-instance

This example starts the local Enterprise Server instance:

<sun-appserv-instance action="start" passwordfile="${passwordfile}"
 instance="${default-instance-name}"/>

Here is an equivalent script showing all the implied attributes:

<sun-appserv-instance
 action="start"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 instance="${default-instance-name}"
 asinstalldir="${asinstalldir}" />

Multiple servers can be controlled using a single command. In this example, two servers are restarted, and in this case each server uses a different password:

<sun-appserv-instance action="restart"
	 instance="${default-instance-name}"/>
<server host="greg.sun.com" passwordfile="${password.greg}"/>
 <server host="joe.sun.com" passwordfile="${password.joe}"/>
</sun-appserv-instance>

This example creates a new Enterprise Server instance:

<sun-appserv-instance
 action="create" instanceport="8080"
 passwordfile="${passwordfile}"
 instance="development" />

Here is an equivalent script showing all the implied attributes:

<sun-appserv-instance
 action="create"
 instanceport="8080"
 user="admin"
 passwordfile="${passwordfile}"
 host="localhost"
 port="4848"
 instance="development"
 asinstalldir="${asinstalldir}" />

Instances can be created on multiple servers using a single command. This example creates a new instance named qa on two different servers. In this case, both servers use the same password.

<sun-appserv-instance
	 action="create"
	 instanceport="8080"
	 instance="qa"
	 passwordfile="${passwordfile}>
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
</sun-appserv-instance>

These instances can also be removed from their respective servers:

<sun-appserv-instance
	 action="delete"
	 instance="qa"
	 passwordfile="${passwordfile}>
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
</sun-appserv-instance>

Different instance names and instance ports can also be specified using attributes of the server subelement:

<sun-appserv-instance action="create" passwordfile="${passwordfile}>
 <server host="greg.sun.com" instanceport="8080" instance="qa"/>
 <server host="joe.sun.com" instanceport="9090"
	 instance="integration-test"/>
</sun-appserv-instance>

The sun-appserv-component Task

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

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.

Table 3–7 The sun-appserv-component Subelements

Element 

Description 

The server Subelement

An Enterprise Server instance 

The component Subelement

A component to be deployed 

The fileset Subelement

A set of component files that match specified parameters 

Attributes of sun-appserv-component

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

Table 3–8 The sun-appserv-component Attributes

Attribute 

Default 

Description 

action

none 

The control command for the target application server. Valid values are enable and disable.

name

file name without extension 

(optional if a component or fileset subelement is present or the file attribute is specified, otherwise required) The display name for the component being enabled or disabled.

file

none 

(optional) The component to enable or disable. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. 

user

admin

(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements.

host

localhost

(optional) Target server. When enabling or disabling a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.

port

4848

(optional) The administration port on the target server. This attribute is inherited by nested server elements.

target

name of default instance 

(optional) Target application server instance. This attribute is inherited by nested server elements.

asinstalldir

see description 

(optional) The installation directory for the local Enterprise Server installation, which is used to find the administrative classes. If not specified, the command checks to see if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

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"
 target="${default-instance-name}"
 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>

Components can be enabled or disabled on multiple servers in a single task. This example shows the same three components being enabled on two different instances of the Enterprise Server. In this example, the passwords for both instances are the same.

<sun-appserv-component action="enable" passwordfile="${passwordfile}">
 <server host="greg.sun.com"/>
 <server host="joe.sun.com"/>
 <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 Enterprise 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.

Subelements of sun-appserv-admin

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

Table 3–9 The sun-appserv-admin Subelements

Element 

Description 

The server Subelement

An Enterprise Server instance 

Attributes of sun-appserv-admin

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

Table 3–10 The sun-appserv-admin Attributes

Attribute 

Default 

Description 

command

none 

(exactly one of these is required: command or explicitcommand) The command to execute. If the user, passwordfile, host, port, or target attributes are also specified, they are automatically inserted into the command before execution. If any of these options are specified in the command string, the corresponding attribute values are ignored.

explicitcommand

none 

(exactly one of these is required: command or explicitcommand) The exact command to execute. No command processing is done, and all other attributes are ignored.

user

admin

(optional) The user name used when logging into the application server administration instance. This attribute is inherited by nested server elements.

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the application server administration instance. This attribute is inherited by nested server elements.

host

localhost

(optional) Target server. If it is a remote server, use the fully qualified host name. This attribute is inherited by nested server elements.

port

4848

(optional) The administration port on the target server. This attribute is inherited by nested server elements.

asinstalldir

see description 

(optional) The installation directory for the local Enterprise Server installation, which is used to find the administrative classes. If not specified, the command checks if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

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 explicitcommand="create-jms-dest --user adminuser --host localhost 
--port 4848 --desttype topic --target server1 simpleJmsDest">

The sun-appserv-jspc Task

Precompiles JSP source code into Enterprise Server compatible Java code for initial invocation by Enterprise 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.

Table 3–11 The sun-appserv-jspc Attributes

Attribute 

Default 

Description 

destdir

none 

The destination directory for the generated Java source files. 

srcdir

none 

(exactly one of these is required: srcdir or webapp) The source directory where the JSP files are located.

webapp

none 

(exactly one of these is required: srcdir or webapp) The directory containing the web application. All JSP files within the directory are recursively parsed. The base directory must have a WEB-INF subdirectory beneath it. When webapp is used, sun-appserv-jspc hands off all dependency checking to the compiler.

verbose

2

(optional) The verbosity integer to be passed to the compiler. 

classpath

none 

(optional) The classpath for running the JSP compiler. 

classpathref

none 

(optional) A reference to the JSP compiler classpath. 

uribase

/

(optional) The URI context of relative URI references in the JSP files. If this context does not exist, it is derived from the location of the JSP file relative to the declared or derived value of uriroot. Only pages translated from an explicitly declared JSP file are affected.

uriroot

see description 

(optional) The root directory of the web application, against which URI files are resolved. If this directory is not specified, the first JSP file is used to derive it: each parent directory of the first JSP file is searched for a WEB-INF directory, and the directory closest to the JSP file that has one is used. If no WEB-INF directory is found, the directory from which sun-appserv-jspc was called is used. Only pages translated from an explicitly declared JSP file (including tag libraries) are affected.

package

none 

(optional) The destination package for the generated Java classes. 

asinstalldir

see description 

(optional) The installation directory for the local Enterprise Server installation, which is used to find the administrative classes. If not specified, the command checks if the asinstalldir parameter has been set. Otherwise, administrative classes must be in the system classpath.

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 Enterprise Server.

For more information about dynamic reloading, see the Sun GlassFish Enterprise Server v2.1.1 Application Deployment Guide.

Attributes of sun-appserv-update

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

Table 3–12 The sun-appserv-update Attributes

Attribute 

Default 

Description 

file

none 

The component to update, which must be a valid archive. 

domain

domain1

(optional) The domain in which the application has been previously deployed. 

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"/>

The wsgen Task

Generates JAX-WS portable artifacts used in JAX-WS web services. Reads a web service endpoint class and generates all the required artifacts for web service deployment and invocation.

Attributes of wsgen

The following table describes attributes for the wsgen task.

Table 3–13 The wsgen Attributes

Attribute 

Default 

Description 

sei

none 

Specifies the name of the service endpoint interface (SEI) class. 

destdir

current directory 

(optional) Specifies where to place the output generated classes. 

classpath

system classpath 

(optional) Specifies where to find the input class files. Same as cp attribute.

cp

system classpath 

(optional) Specifies where to find the input class files. Same as classpath attribute.

resourcedestdir

current directory 

(optional) Specifies where to place generated resource files such as WSDL files. Used only if the genwsdl attribute is set to true.

sourcedestdir

current directory 

(optional) Specifies where to place generated source files. 

keep

false

(optional) If true, keeps generated files.

verbose

false

(optional) If true, outputs compiler messages.

genwsdl

true

(optional) If true, generates a WSDL file.

protocol

soap1.1

(optional) Specifies the protocol to use in the wsdl:binding. Used only if the genwsdl attribute is set to true.

Allowed values are soap1.1 or Xsoap1.2. Xsoap1.2 is not standard and is only used if the extension attribute is set to true.

servicename

none 

(optional) Specifies a particular wsdl:service name for the generated WSDL file. Used only if the genwsdl attribute is set to true. For example:

servicename="{http://mynamespace/}MyService"

portname

none 

(optional) Specifies a particular wsdl:port name for the generated WSDL. Used only if the genwsdl attribute is set to true. For example:

portname="{http://mynamespace/}MyPort"

extension

false

(optional) If true, allows vendor extensions not in the specification. Use of extensions may result in applications that are not portable and may not interoperate with other implementations.

Example of wsgen

The following example generates portable artifacts for fromjava.server.AddNumbersImpl, uses compile.classpath as the classpath, and writes the WSDL file to ${wsdl.dir}.

<wsgen
   resourcedestdir="${wsdl.dir}"
   sei="fromjava.server.AddNumbersImpl">
   <classpath refid="compile.classpath"/>
</wsgen>

The wsimport Task

Generates JAX-WS portable artifacts for a given WSDL file. Portable artifacts include service endpoint interfaces (SEIs), services, exception classes mapped from the wsdl:fault and soap:headerfault tags, asynchronous response beans derived from the wsdl:message tag, and JAXB generated value types. After generation, these artifacts can be packaged in a WAR file with the WSDL and schema documents along with the endpoint implementation and then deployed.

Attributes of wsimport

The following table describes attributes for the wsimport task.

Table 3–14 The wsimport Attributes

Attribute 

Default 

Description 

wsdl

none 

Specifies the name of the WSDL file. 

destdir

current directory 

(optional) Specifies where to place the output generated classes. 

sourcedestdir

current directory 

(optional) Specifies where to place generated source files. Used only if the keep attribute is set to true.

keep

false

(optional) If true, keeps generated files.

verbose

false

(optional) If true, outputs compiler messages.

binding

none 

(optional) Specifies external JAX-WS or JAXB binding files. JAX-WS and JAXB binding files can customize things like package names and bean names. More information on JAX-WS and JAXB binding files can be found in the customization documentation included with this release. 

extension

false

(optional) If true, allows vendor extensions not in the specification. Use of extensions may result in applications that are not portable and may not interoperate with other implementations.

wsdllocation

none 

(optional) Specifies the value of @WebService.wsdlLocation and @WebServiceClient.wsdlLocation annotation elements for the generated SEI and Service interface. This should be set to the URI of the web service WSDL file.

catalog

none 

(optional) Specifies the catalog file to resolve external entity references. Supported formats are TR9401, XCatalog, and OASIS XML Catalog. Additionally, the Ant xmlcatalog type can be used to resolve entities.

package

none 

(optional) Specifies the target package, overriding any WSDL and schema binding customization for package name, and the default package name algorithm defined in the JAX-WS specification. 

Example of wsimport

The following example generates client-side artifacts for AddNumbers.wsdl and stores .class files in the ${build.classes.home} directory using the custom.xml customization file.

<wsimport
   destdir="${build.classes.home}"
   wsdl="AddNumbers.wsdl"
   binding="custom.xml">
</wsimport>

Reusable Subelements

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

The server Subelement

Specifies an Enterprise Server instance. Allows a single task to act on multiple server instances. The server attributes override corresponding attributes in the parent task; therefore, the parent task attributes function as default values.


Note –

Some topics in the documentation pertain to features that are available only in domains that are configured to support clusters. Examples of domains that support clusters are domains that are created with the cluster profile or the enterprise profile. For information about profiles, see Usage Profiles in Sun GlassFish Enterprise Server v2.1.1 Administration Guide.


Attributes of server

The following table describes attributes for the server element.

Table 3–15 The server Attributes

Attribute 

Default 

Description 

user

admin

(optional) The user name used when logging into the Enterprise Server domain administration server (DAS). 

passwordfile

none 

(optional) File containing passwords. The password from this file is retrieved for communication with the Enterprise Server DAS. 

host

localhost

(optional) Target server. When targeting a remote server, use the fully qualified host name. 

port

4848

(optional) The administration port on the target server. 

instance

name of default instance 

(optional) Target application server instance. 

instanceport

none 

(applies to The sun-appserv-instance Task only) Deprecated.

nodeagent

none 

(applies to The sun-appserv-instance Task only, required if action is create, otherwise ignored) The name of the node agent on which the instance is being created.

debug

false

(applies to The sun-appserv-instance Task only, optional) Deprecated. If action is set to start, specifies whether the server starts in debug mode. This attribute is ignored for other values of action. If true, the instance generates additional debugging output throughout its lifetime.

upload

true

(applies to The sun-appserv-deploy Task only, optional) If true, the component is transferred to the server for deployment. If the component is being deployed on the local machine, set upload to false to reduce deployment time.

virtualservers

default virtual server only 

(applies to The sun-appserv-deploy Task only, optional) A comma-separated list of virtual servers to be deployment targets. This attribute applies only to application (.ear) or web (.war) components and is ignored for other component types.

Examples of server

You can control multiple servers using a single task. In this example, two servers are started, each using a different password. Only the second server is started in debug mode.

<sun-appserv-instance action="start">
<server host="greg.sun.com" passwordfile="${password.greg}"/>
<server host="joe.sun.com" passwordfile="${password.joe}"
	 debug="true"/>
</sun-appserv-instance>

You can create instances on multiple servers using a single task. This example creates a new instance named qa on two different servers. Both servers use the same password.

<sun-appserv-instance action="create" instanceport="8080"
	 instance="qa" passwordfile="${passwordfile}>
<server host="greg.sun.com"/>
<server host="joe.sun.com"/>
</sun-appserv-instance>

These instances can also be removed from their respective servers:

<sun-appserv-instance action="delete" instance="qa"
	 passwordfile="${passwordfile}>
<server host="greg.sun.com"/>
<server host="joe.sun.com"/>
</sun-appserv-instance>

You can specify different instance names and instance ports using attributes of the nested server element:

<sun-appserv-instance action="create" passwordfile="${passwordfile}>
<server host="greg.sun.com" instanceport="8080" instance="qa"/>
<server host="joe.sun.com" instanceport="9090"
	instance="integration-test"/>
</sun-appserv-instance>

You can deploy multiple components to multiple servers (see the The component Subelement) . This example deploys each component to two Enterprise Server instances running on remote servers. Both servers use the same password.

<sun-appserv-deploy passwordfile="${passwordfile}" 
  asinstalldir="/opt/s1as8" >
<server host="greg.sun.com"/>
<server host="joe.sun.com"/>
<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 from multiple servers. This example shows the same three components being removed from two different instances. Both servers use the same password.

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

You can enable or disable components on multiple servers. This example shows the same three components being enabled on two different instances. Both servers use the same password.

<sun-appserv-component action="enable" passwordfile="${passwordfile}">
<server host="greg.sun.com"/>
<server host="joe.sun.com"/>
<component file="${assemble}/simpleapp.ear"/>
<component file="${assemble}/simpleservlet.war"/>
<component name="simplebean" />
</sun-appserv-component>

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.

Table 3–16 The component Attributes

Attribute 

Default 

Description 

file

none 

(optional if the parent task is The sun-appserv-undeploy Task or The sun-appserv-component Task) The target component. If this attribute refers to a file, it must be a valid archive. If this attribute refers to a directory, it must contain a valid archive in which all components have been exploded. If upload is set to false, this must be an absolute path on the server machine.

name

file name without extension 

(optional) The display name for the component. 

force

true

(applies to The sun-appserv-deploy Task only, optional) If true, the component is overwritten if it already exists on the server. If false, the containing element’s operation fails if the component exists.

precompilejsp

false

(applies to The sun-appserv-deploy Task only, optional) If true, all JSP files found in an enterprise application (.ear) or web application (.war) are precompiled. This attribute is ignored for other component types.

retrievestubs

client stubs not saved 

(applies to The sun-appserv-deploy Task only, optional) The directory where client stubs are saved.

contextroot

file name without extension 

(applies to The sun-appserv-deploy Task only, optional) The context root for a web module (WAR file). This attribute is ignored if the component is not a WAR file.

verify

false

(applies to The sun-appserv-deploy Task only, optional) If true, syntax and semantics for all deployment descriptors is automatically verified for correctness.

Examples of component

You can deploy multiple components using a single task. This example deploys each component to the same Enterprise Server instance 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 deploy multiple components to multiple servers. This example deploys each component to two instances running on remote servers. Both servers use the same password.

<sun-appserv-deploy passwordfile="${passwordfile}" asinstalldir="/opt/s1as8" >
<server host="greg.sun.com"/>
<server host="joe.sun.com"/>
<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 to multiple servers. This example shows the same three components being removed from two different instances. Both servers use the same password.

<sun-appserv-undeploy passwordfile="${passwordfile}">
<server host="greg.sun.com"/>
<server host="joe.sun.com"/>
<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>

You can enable or disable multiple components on multiple servers. This example shows the same three components being enabled on two different instances. Both servers use the same password.

<sun-appserv-component action="enable" passwordfile="${passwordfile}">
<server host="greg.sun.com"/>
<server host="joe.sun.com"/>
<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.

JBI Tasks

The asant utility supports the Java Business Integration (JBI) Ant tasks. The Ant Tasks Reference is included with the Enterprise Server at as-install/jbi/doc/antdoc/.

For more information about JBI in the Enterprise Server, see JBI Runtime.

Chapter 4 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 Admin Console. In the developer profile, select the Enterprise Server component and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration.

  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 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 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 GlassFish Enterprise Server v2.1.1 Reference Manual.

Application Client Debugging

When the appclient script executes the java command to run the Application Client Container (ACC), which in turn runs the client, it includes on the command line the value of the VMARGS environment variable. You can set this variable to any suitable value. The following example debugging setup is for Windows systems:


VMARGS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8118

The following example debugging setup is for UNIX-based systems:


set VMARGS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8118

For debugging an application client, you should set suspend to y so you can connect the debugger to the client before any code has actually executed. Otherwise, the client may start running and execute past the point you want to examine.

You should use different ports for the server and client if you are debugging both concurrently. For details about setting the port, see JPDA Options.

For information about the appclient script, see Sun GlassFish Enterprise Server v2.1.1 Reference Manual.

Sun GlassFish Message Queue Debugging

Sun GlassFish 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 GlassFish Message Queue 4.4 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 as-install/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/javase/6/docs/technotes/tools/share/jstack.html) or the command kill -QUIT process_id.

Enterprise Server Logging

You can use the Enterprise Server’s log files to help debug your applications. Use the Admin Console. In the developer profile, select the Enterprise Server component. In the cluster profile, select the Stand-Alone Instances component, and select the instance from the table. Then click the View Log Files button in the General Information page.

To change logging settings in the developer profile, select the Logging tab. In the cluster profile, select Logger Settings under the relevant configuration.

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 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 Admin Console. In the developer profile, select the Enterprise Server component and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration. 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 Admin Console:

    1. In the developer profile, select the Enterprise Server component and the JVM Settings tab. In the cluster profile, select the JVM Settings component under the relevant configuration. 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 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 – 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.