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 Oracle GlassFishTM Server.
Setting up an environment for creating, assembling, deploying, and
debugging your code involves installing the mainstream version of
the GlassFish Server and making use of development tools. In addition,
sample applications are available. These topics are covered in the
following sections:

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 Oracle GlassFish Server 3.0.1 Reference Manual.

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

The Administration Console

The Administration Console lets
you configure the server and perform both administrative and development
tasks using a web browser. For general information about the Administration Console,
click the Help button in the Administration Console. This displays the GlassFish 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 GlassFish Server is running. By default, the host is localhost. For example:

Scripting Language Support

The Migration Tool

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

The NetBeans IDE

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

The Eclipse IDE

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

Debugging Tools

Profiling Tools

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

Sample Applications

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

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 6 sample applications, samples
are also available at GlassFish Samples and at as-install/glassfish/samples/.

Chapter 2 Class Loaders

Understanding Oracle GlassFishTM 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:

The Web Profile of
the GlassFish Server supports the EJB 3.1 Lite specification, which allows
enterprise beans within web applications, among other features. The
full GlassFish Server supports the entire EJB 3.1 specification. For
details, see JSR 318.

The Class Loader Hierarchy

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

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

Public
API

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

Common

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

Connector

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

LifeCycleModule

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

Applib

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

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

Archive

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

Delegation

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

The Java Servlet specification recommends
that a web module's class loader look in the local class loader before
delegating to its parent. You can make this 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 Oracle GlassFish Server 3.0.1 Application Deployment Guide.

The default value is delegate="true", which
causes a web module's 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 Oracle GlassFish Server 3.0.1 Application Deployment Guide.

For a number of packages,
including java.* and javax.*,
symbol resolution is always delegated to the parent class loader regardless
of the delegate setting. This prevents applications
from overriding core Java runtime classes or changing the API versions
of specifications that are part of the Java EE platform.

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.

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 Applib and Archive class loaders.

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

Individually Deployed Module
Universe – Each individually deployed EJB JAR 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 library-directory element
in the application.xml deployment descriptor

A directory pointed to by the application or module’s
classpath; for example, a web module’s classpath includes these
directories:

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

Application-Specific Class Loading

You can specify module- or application-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 application or module.
Select the Deploy button. Type the comma-separated paths in the Libraries
field. For details, click the Help button in the Administration Console.

The
Libraries field in the Administration Console's deployment page and the ----libraries option of the asadmin
deploy command do not apply to application clients. For
more information, see Using Libraries with Application Clients.

You can only specify module-
or application-specific library classes during deployment. You can
update a library JAR file using dynamic reloading or by restarting
(disabling and re-enabling) a module or application. To add or remove
library JAR files, you must redeploy the module or application.

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

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.

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 or modules 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 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 (and other needed files, such as .properties 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. However, this accessibility does not extend to
application clients. For more information, see Using Libraries with Application Clients.

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.

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.

To Package the Client JAR for One Application
in Another 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.

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.

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 Using
Ant with GlassFishTM Server

The Oracle GlassFish Server provides server-specific Ant tasks,
which are described in the following sections:

GlassFish Server is
compatible with Apache Ant versions 1.6.5 or greater. If you don't
have Ant installed, you can download it from the Update Tool. The
Apache Ant Build Tool add-on component supplies Ant version 1.7.1.
For more information about the Update Tool, see Update Tool in Oracle GlassFish Server 3.0.1 Administration Guide.

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

Setting Up Your Ant Environment

To set up your Ant environment for using GlassFish Server Ant tasks,
you can either define the ANT_OPTS environment variable
or define a target. In both these cases, you must also set the classpath
to point to the sun-appserv-ant.jar file.

Defining the ANT_OPTS Variable

To define the ANT_OPTS environment variable on
UNIX systems, use the following commands, where ${ASINSTALLDIR} is
an environment variable defined to point to the GlassFish Server installation
directory.

To define the ANT_OPTS environment variable on
Windows systems, use the following commands, where %ASINSTALLDIR% is an environment variable defined to point to the GlassFish Server installation
directory.

set ANT_OPTS="-Djava.library.path=%ASINSTALLDIR%\modules"
set CLASSPATH=%CLASSPATH%;%ASINSTALLDIR%\modules\sun-appserv-ant.jar

Defining a Target

The following target element defines the GlassFish Server Ant
tasks and references the sun-appserv-ant.jar file.
You can include this target in your build.xml file.
The ${asinstalldir} in the classpath element
refers to the GlassFish Server installation directory.

Ant resolves properties from top to bottom in Ant build files.
If you define the GlassFish Server Ant tasks at the project level, make
sure that any properties used within the task definitions have been
resolved before the task definitions. For example, the following snippet
defines the sun-appserv-admin task at the project
level:

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, mysql, 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.

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

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

(optional) A deployment plan is a JAR file containing GlassFish Server descriptors.
Use this attribute when deploying an EAR file that lacks GlassFish Server 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 GlassFish 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 GlassFish 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.

(optional) The installation directory for the local GlassFish 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 web application deployment script
with many implied attributes:

This example deploys multiple components to two GlassFish 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.

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.

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.

(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 GlassFish 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 GlassFish 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.

(optional) The installation directory for the local GlassFish 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:

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.

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 GlassFish Server. In this example, the passwords for both instances
are the same.

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 server instance.
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.

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 or
an already referenced stand-alone configuration (including the administration
server configuration server-config).

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.

(optional) The user name used when logging into the GlassFish 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 GlassFish 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.

(optional) The installation directory for the local GlassFish 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.

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 server instance.
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 GlassFish 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 GlassFish 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.

(optional) The installation directory for the local GlassFish 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.

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 GlassFish Server. In this example,
the passwords for both instances are the same.

The sun-appserv-admin Task

Enables arbitrary administrative commands and scripts to be
executed on the GlassFish 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.

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

The sun-appserv-jspc Task

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

The sun-appserv-update Task

Enables deployed web 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 GlassFish Server.

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.

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

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

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.

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

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/Types/fileset.html.

Chapter 4 Debugging Applications

This chapter gives guidelines for debugging applications in
the Oracle GlassFishTM Server. It includes the
following sections:

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

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

You can enable debugging even when the GlassFish Server is started
without the ----debug option. This
is useful if you start the GlassFish Server from the Windows Start Menu,
or if you want to make sure that debugging is always turned on.

To Set the Server to Automatically Start Up
in Debug Mode

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

Check the Debug Enabled box.

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.

See Also

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

JPDA Options

The default JPDA options in GlassFish Server are as follows:

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

For Windows, you can change dt_socket to dt_shmem.

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

To specify a different port (from 9009, the default) to use
when attaching the JVM software to a debugger, specify address=port-number.

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 Oracle GlassFish Server 3.0.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. For example:

set VMARGS=-Xdebug -agentlib:jdwp=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.

GlassFish Message Queue Debugging

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 Oracle GlassFish Message Queue 4.4.2 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 --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 -QUITprocess_id.

GlassFish Server Logging

You can use the GlassFish Server’s log files to help debug
your applications. Use the Administration Console. Select the GlassFish Server component. Then click the View Log
Files button in the General Information page.

To change logging settings,
select the Logging tab.

For details about logging, click the Help button in the Administration Console.

Profiling Tools

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

The NetBeans Profiler

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.