asadmin Utility Syntax

The replaceable items in this syntax are described in the subsections
that follow. For full details of this syntax, see the asadmin(1M) help page.

Subcommands of the asadmin Utility

The subcommand identifies the operation or task
that you are performing. Subcommands are case-sensitive. Each subcommand is
either a local subcommand or a remote subcommand.

A local subcommand can be run without
a running domain administration server (DAS). However, to run the subcommand
and have access to the installation directory and the domain directory, the
user must be logged in to the machine that hosts the domain.

A remote subcommand is always run by
connecting to a DAS and running the subcommand there. A running DAS is required.

asadmin Utility Options
and Subcommand Options

Options control the behavior of the asadmin utility
and its subcommands. Options are case-sensitive.

The asadmin utility has the following types of options:

asadmin utility
options. These options control the behavior of the asadmin utility,
not the subcommand. The asadmin utility options may precede
or follow the subcommand, but asadmin utility options after
the subcommand are deprecated. All asadmin utility options
must either precede or follow the subcommand. If asadmin utility
options are specified both before and after the subcommand, an error occurs.
For a description of the asadmin utility options, see the asadmin(1M) help page.

Subcommand Options. These
options control the behavior of the subcommand, not the asadmin utility.
Subcommand options must follow the subcommand. For a description of a subcommand’s
options, see the entry for the subcommand in Oracle GlassFish Server 3.0.1 Reference Manual.

Note –

Not all subcommand options are supported for this release of GlassFish Server.
If you specify an unsupported option, a syntax error does not occur. Instead,
the command runs successfully and the unsupported option is silently ignored.

A subcommand option may have the same name as an asadmin utility
option, but the effects of the two options are different.

Options have a long form and a short form.

The short form of an option has a single dash (-)
followed by a single character.

The long form of an option has two dashes (--)
followed by an option word.

For example, the short form and the long form of the option for specifying
terse output are as follows:

Short form: -t

Long form: --terse

Most options require argument values, except Boolean options, which
toggle to enable or disable a feature.

Operands of asadmin Utility
Subcommands

Operands specify the items on which the subcommand is to act. Operands
must follow the argument values of subcommand options, and are set off by
a space, a tab, or double dashes (--). The asadmin utility
treats anything that follows the subcommand options and their values as an
operand.

To Run an asadmin Utility
Subcommand in Single Mode

In single mode, you must type a separate asadmin command
for each subcommand that you want to use. After the subcommand has run, you
are returned to the operating system's command shell. Any asadmin utility
options must be specified in each separate asadmin command
that you run. If you require the same asadmin utility options
for multiple subcommands, use the asadmin utility in multimode.
For more information, see To Start a Multimode Session.

In the operating system's command shell, run the asadmin utility,
specifying the subcommand.

If necessary, also specify any required asadmin utility options, subcommand options, and operands.

Example 2–1 Running an asadmin Utility Subcommand in Single
Mode

This example runs the list-applications(1) subcommand in single mode.
In this example, the default values for all options are used.

The example shows that the application hello is deployed
on the local host.

Example 2–3 Specifying an asadmin Utility Option and a Subcommand
Option in Single Mode

This example specifies the --hostasadmin utility option and the --type subcommand
option with the list-applications subcommand in single
mode. In this example, the DAS is running on the host srvr1.example.com and
applications of type web are to be listed.

To Display Help Information for the asadmin Utility or a Subcommand

GlassFish Server provides help information about the syntax, purpose, and
options of the asadmin utility and its subcommands. This
help information is written in the style of UNIX platform
man pages. This help information is also available in Oracle GlassFish Server 3.0.1 Reference Manual.

If you are displaying help information for a remote subcommand,
ensure that the server is running.

Remote subcommands require
a running server.

Specify the subcommand of interest as the operand of the help subcommand.

If you run the help subcommand
without an operand, help information for the asadmin utility
is displayed.

Example 2–4 Displaying Help Information for the asadmin Utility

This example displays the help information for the asadmin utility.

asadmin help

Example 2–5 Displaying Help Information for an asadmin Utility
Subcommand

This example displays the help information for the create-jdbc-resource subcommand.

asadmin help create-jdbc-resource

See Also

To display the available subcommands, use the list-commands(1) subcommand. Local subcommands are displayed before
remote subcommands. If the server is not running, only local subcommands are
displayed.

To Start a Multimode Session

The asadmin utility can be used in multiple command
mode, or multimode. In multimode, you run the asadmin utility once to start a multimode session. During the session,
the asadmin utility continues to accept subcommands until
you end the session and return to the operating system's command shell. Any asadmin utility options that you set for your multimode session
are used for all subsequent subcommands in the session.

Starting a Multimode Session From Within an Existing
Multimode Session

You can start a multimode session from within an existing session by
running the multimode subcommand from within the existing
session. After you end the second multimode session, you return to your original
multimode session.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help multimode at the command line.

To End a Multimode Session

At the asadmin> prompt, type
one of the following commands or key combinations:

exit

quit

UNIX and Linux systems:
Ctrl-D

Windows systems: Ctrl-Z

You are returned to the operating system's command shell and the asadmin> prompt is no longer displayed. If the asadmin> prompt is still displayed, you might have opened a multimode
session within a multimode session. In this situation, repeat this procedure
to end the remaining multimode session.

To Run a Set of asadmin Subcommands
From a File

Running a set of asadmin subcommands from a file
enables you to automate repetitive tasks.

Create a plain text file that contains the sequence of subcommands
that you want to run.

Run the multimode(1) subcommand,
specifying the file that you created.

If necessary, also specify
any asadmin utility options that are required to enable
subcommands in the file to run.

Example 2–9 Running a Set of asadmin Subcommands From a File

This example contains the following:

A listing of a file that is named commands_file.txt,
which contains a sequence of asadmin subcommands

The command to run the subcommands in the file commands_file.txt

The commands_file.txt file contains the asadmin utility subcommands to perform the following sequence of operations:

This example runs the sequence of subcommands in the commands_file.txt file. Because the --portbase option
is specified for the create-domain subcommand in the file,
the --portasadmin utility
option must also be set.

asadmin --port 9048 multimode --file commands_file.txt

See Also

For more information about the subcommands in the preceding example,
see the following help pages:

Administering System Properties

Shared server instances will often need
to override attributes defined in their referenced configuration. Any configuration
attribute can be overridden through a system property of the corresponding
name.

To Create System Properties

Use the create-system-properties subcommand in remote
mode to create or update one or more system properties of the domain or configuration. Any
configuration attribute can be overwritten through a system property of the
corresponding name.

Example 2–12 Deleting a System Property

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-system-property at the command line.

Administering Resources

This section contains instructions for integrating resources into the GlassFish Server environment.
Information about administering specific resources, such as JDBC, is contained
in other chapters.

To Add Resources From an XML File

Use the add-resources subcommand in remote mode to
create the resources named in the specified XML file. The following resources
are supported: JDBC connection pool and resource, JMS, JNDI, and JavaMail
resources, custom resource, connector resource and work security map, admin
object, and resource adapter configuration.

The XML file must reside in the as-install/domains/domain1/config directory. If you specify a relative path or simply provide the
name of the XML file, this subcommand will prepend as-install/domains/domain1/config to this operand.

Listing Various System Elements

To Display the GlassFish Server Version

Use the version subcommand in remote mode to display
information about the GlassFish Server version for a particular server. If the
subcommand cannot communicate with the server by using the specified login
(user/password) and target (host/port) information, then the local version
is displayed along with a warning message.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-containers at the command line.

To List Modules

Use the list-modules subcommand in remote mode to
list the modules that are accessible to the GlassFish Server module subsystem.
The status of each module is included. Possible statuses include NEW and READY.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-modules at the command line.

To List Subcommands

Use the list-commands subcommand in remote mode to
list the deployed asadmin subcommands. You can specify
that only remote subcommands or only local subcommands are listed. By default,
this subcommand displays a list of local subcommands followed by a list of
remote subcommands.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-commands at the command line.

To List Timers

The timer service is a persistent and transactional notification service
that is provided by the enterprise bean container and is used to schedule
notifications or events used by enterprise beans. All enterprise beans except
stateful session beans can receive notifications from the timer service. Persistent
timers set by the service are not destroyed when the server is shut down or
restarted.

Use the list-timers subcommand in remote mode to
list the persistent timers owned by a specific server instance.
You can use this information to decide whether to do a timer migration, or
to verify that a migration has been completed successfully.

Example 2–20 Showing Status of a Component

Using REST Interfaces to Administer GlassFish Server

GlassFish Server provides representational state transfer (REST) interfaces
to enable you to access monitoring and configuration data for GlassFish Server,
including data that is provided by newly installed add-on components.

You can access the GlassFish Server REST interfaces through client applications
such as:

Using REST URLs to Administer GlassFish Server

Each node in the configuration and monitoring object trees is represented
as a REST resource that is accessible through an HTTP uniform resource locator
(URL). Access to REST resources for GlassFish Server monitoring and configuration
data requires a running DAS.

The formats of the URLs to resources that represent nodes in the configuration
and monitoring object trees are as follows:

Configuration:http://host:port/management/domain/path

Monitoring:http://host:port/monitoring/domain/path

The replaceable items in these URLs are as follows:

host

The host where the DAS is running.

port

The HTTP port or HTTPS port for administration.

path

The
path to the node. The path is the dotted name of the node in which each dot
(.) is replaced with a slash (/). For
more information, see the following documentation:

If the URL to a REST resource for GlassFish Server monitoring or configuration
data is opened in a web browser, the browser displays a web page that contains
the following information about the resource:

A list of the attributes of the resource and their values.
If the resource represents a node in the configuration tree, these attributes
are presented in an HTML form that you can use to update the resource. Attributes
of a resource for a node in the monitoring tree are read only.

A list of hypertext links to the children of the resource.
This list of links enables you to traverse the tree that contains the resource
and to discover the all resources in the tree.

The following figure shows the web page for the REST resource for managing
a domain.

Figure 2–1 Web Page for the REST Resource for Managing a Domain

Using REST Resource Methods to Administer GlassFish Server

The GlassFish Server REST interfaces support methods for accessing nodes
in the monitoring and configuration object trees.

The following table shows the REST methods for administering monitoring
and configuration data and the tasks that you can perform with each method.
These methods are HTTP 1.1 primitives. For the detailed specification of these
primitives, see Hypertext Transfer Protocol -- HTTP/1.1.

Determine the methods and method parameters that a node in the tree
supports

OPTIONS or GET

Retrieve data for a node in the tree

GET

Add a node to the tree

POST

Update a node in the tree

POST

Delete a node from the tree

DELETE

Note –

The GET method can be used instead of
the OPTIONS method to determine the methods and method
parameters that a node in the tree supports. The GET method
also provides additional information about the node. For details, see To Retrieve Data for a Node in the Tree.

To Determine the Methods and Method Parameters
That a Node in the Tree Supports

The methods and method parameters that a node in the tree supports depend
on the REST resource that represents the node:

REST resources for monitoring support only the GET method.

All REST resources for configuration support the GET method
and the OPTIONS method. However, only some REST resources
for configuration also support the POST method and
the DELETE method.

Before performing any operations on a node in the tree, determine the
methods and method parameters that the node supports.

Use the appropriate method on the REST resource that represents
the node.

If the node is in the monitoring object tree, use the GET method.

If the node is in the configuration object tree, use the OPTIONS method or the GET method.

The GET method and the OPTIONS method
return the list of methods that the resource supports. For each method, the
list of acceptable message parameters or the list of acceptable query parameters
are returned.

Example 2–21 Determining the Methods and Method Parameters That a Node in the Tree
Supports

This example uses the cURL utility to determine the methods and method
parameters that the resource for the domain supports. The example uses the
following options of the cURL utility:

-X to specify that the OPTIONS method
is used

-H to specify that the resource is represented
in JavaScript Object Notation (JSON)

In this example, the DAS is running on the local host and the HTTP port
for administration is 4848. In addition to the OPTIONS method,
the resource supports the POST method and the GET method.

This step updates the REST resource jdbc-myjdbcresource to
disable the JDBC resource that jdbc-myjdbcresource represents.
The -d option of the cURL utility sets the enabled message
parameter to disabled.

Child Resources for Non-CRUD Operations

The GlassFish Server REST interfaces also support operations other than
create, read, update, and delete (CRUD) operations, for example:

State management

Queries

Application deployment

These operations are supported through child resources of the resource
on which the operation is performed. The child resources do not represent
nodes in the configuration object tree.

For example, the resource for managing a domain provides child resources
for non-CRUD operations as shown in the following table.

Table 2–2 Child Resources for Non-CRUD Operations
on a Domain

Resource

Action

host-port

Displays the host on which the DAS is running and the port on which
the DAS listens for HTTP requests.

restart

Stops and then restarts the DAS of the domain.

rotate-log

Rotates the server log file by renaming the file with a timestamp name
in the format server.log_date-and-time,
and creating an empty log file.

stop

Stops the DAS of the domain.

uptime

Displays the length of time that the DAS has been running since it was
last restarted.

version

Displays version information for GlassFish Server.

Securing GlassFish Server REST Interfaces

The GlassFish Server REST interfaces support basic authentication over
a secure connection. When security is enabled, you must specify https as
the protocol in the URLs to REST resources and provide a username and password.

Formats for Resource Representation

How to specify the resource representation depends on how you are accessing
the GlassFish Server REST interfaces. For example, if you are using the cURL
utility, specify the resource representation through the -H option
as follows:

For JSON, specify -H "Accept: application/json".

For XML, specify -H "Accept: application/xml".

For HTML, omit the -H option.

JSON Resource Representation

The general format for the JSON representation of a resource is as follows:

JSON Representation of a Message Parameter
or a Query Parameter

The JSON representation of a message parameter or a query parameter
is as follows:

"parameter-name":{attribute-list}

The replaceable items in this format are as follows:

parameter-name

The name of the parameter.

attribute-list

A comma-separated list of name-value pairs of attributes for
the parameter. Each pair is in the following format:

"name":"value"

Possible attributes are as follows:

Default Value

The default value of the parameter.

Acceptable Values

The set or range of acceptable values for the parameter.

Type

The data type of the parameter, which is one of the following
types:

boolean

int

string

Optional

Indicates whether the parameter is optional. If true,
the parameter is optional. If false, the parameter is required.

Key

Indicates whether the parameter is key. If true,
the parameter is key. If false, the parameter is not key.

Example JSON Resource Representation

This example shows the JSON representation of the resource for managing
a domain. In this example, the DAS is running on the local host and the HTTP
port for administration is 4848. The URL to the resource in this example is http://localhost:4848/management/domain.

Zero or more XML elements that specify the URLs of child resources.
Each element is specified as <child-resource>url</child-resource>,
where child-resource is the name of the child resource
and url is the URL to the child resource.

XML Representation of a Message Parameter
or a Query Parameter

The XML representation of a message parameter or a query parameter is
as follows:

<parameter-nameattribute-list/>

The replaceable items in this format are as follows:

parameter-name

The name of the parameter.

attribute-list

A space-separated list of name-value pairs of attributes for
the parameter. Each pair is in the following format:

name="value"

Possible attributes are as follows:

Default Value

The default value of the parameter.

Acceptable Values

The set or range of acceptable values for the parameter.

Type

The data type of the parameter, which is one of the following
types:

boolean

int

string

Optional

Indicates whether the parameter is optional. If true,
the parameter is optional. If false, the parameter is required.

Key

Indicates whether the parameter is key. If true,
the parameter is key. If false, the parameter is not key.

Example XML Resource Representation

This example shows the XML representation of the resource for managing
a domain. In this example, the DAS is running on the local host and the HTTP
port for administration is 4848. The URL to the resource in this example is http://localhost:4848/management/domain.

HTML Resource Representation

The format for the HTML representation of a resource is a web page that
provides the following information about the resource:

A list of the attributes of the resource and their values.

A list of the methods and method parameters that the resource
supports. Each method and its parameters are presented as a field of the appropriate
type in an HTML form.

A list of hypertext links to the children of the resource.

For a sample web page, see Figure 2–1.
In this example, the DAS is running on the local host and the HTTP port for
administration is 4848. The URL to the resource in this example is http://localhost:4848/management/domain.

Chapter 3 Administering Domains

This chapter provides procedures for administering domains in the Oracle GlassFish Server 3.0.1 environment
by using the asadmin command-line utility.

Instructions for accomplishing the tasks in this chapter by using the Administration Console are
contained in the Administration Console online help.

About Administering Domains (or Servers)

A domain is a group of instances that are administered
together. The domain provides a preconfigured runtime for user applications.
In addition to providing an administration boundary, a domain provides the
basic security structure whereby separate administrators can administer specific
groups of server instances. By grouping the server instances into separate
domains, different organizations and administrators can share a single installation
of GlassFish Server. A domain has its own configuration, log files, and application
deployment areas that are independent of other domains. If the configuration
is changed for a domain, the configurations for other domains are not affected.

The GlassFish Server installer creates a default administrative domain
named domain1, as well as an associated domain administration
server (DAS) named server. The DAS is a specially-designated
instance that authenticates the administrator, accepts requests from administration
tools, and communicates with server instances in the domain to carry out requests.
The DAS is sometimes referred to as the default server because
it is the only server instance created during GlassFish Server installation that
can be used for deployment.

The default administration
port is 4848, but a different port can be specified during installation. When
a domain is created, you are prompted for the administration user name and
password, but you can accept the default in which case user name is admin and there is no password. To reset the administration password,
see To Change the Administration Password.

The graphical Administration Console communicates with a specific DAS to administer
the domain associated with the DAS. Each Administration Console session enables you
to configure and manage the specific domain. If you create multiple domains,
you must start a separate Administration Console session to manage each domain.

Creating, Logging In To, and Deleting a
Domain

To Create a Domain

After installing GlassFish Server and creating the default domain (domain1), you can create additional domains by using the local create-domain subcommand. This subcommand creates the configuration of a domain.
Any user who has access to the asadmin utility on a given
system can create a domain and store the domain configuration in a folder
of choice. By default, the domain configuration is created in the default
directory for domains. You can override this location to store the configuration
elsewhere.

You are required to specify an administrative user when you create a
domain, or you can accept the default login identity which is username admin with no password.

Before You Begin

Determine which profile will apply to the domain.

Select a name for the domain that you are creating.

You
can verify that a name is not already in use by using the list-domains(1) subcommand

To start the Administration Console in a browser, enter the URL in the following
format:

http://hostname:5000

For this example, the domain’s log files, configuration files,
and deployed applications now reside in the following directory:

domain-root-dir/mydomain

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help create-domain at the command line.

To List Domains

Use the list-domains subcommand to display a list
of domains and their statuses. If the domain directory is not specified, the
contents of the default as-install/domains directory
is listed. If there is more than one domain, the domain name must be specified.

To list domains that were created in other directories, specify the --domaindir option.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-domain at the command line.

To Log In to a Domain

All remote subcommands require that credentials be specified in terms
of an administration user name and its password. By default, the domain is
created with an identity that allows an asadmin user to
perform administrative operations when no identity is explicitly or implicitly
specified.

The default identity is in the form of a user
whose name is admin and has no password. If you specify
no user name on the command line or on prompt, and specify no password in
the --passwordfile option or on prompt,
and you have never logged in to a domain using either the login subcommand
or the create-domain subcommand with the ----savelogin option, then the asadmin utility
will attempt to perform a given administrative operation without specifying
any identity.

A server (domain) allows administrative operations to be run using this
default identity if the following conditions are true:

If this condition is not true, you will
need to specify the user name and password.

The file realm has one and only one user (what the user name
is does not matter).

If this condition is not true, you will also
need to specify the user name.

That one user has no password.

If this condition
is not true, you will need to specify the password.

By default, all of these conditions are true, unless you have created
the domain with a specific user name and password. Thus, by default, the only
administrative user is admin with no password.

Use the login subcommand in local mode to authenticate
yourself (log in to) a specific domain. After such login, you do not need
to specify the administration user or password for subsequent operations on
the domain. The login subcommand can only be used to specify
the administration password. For other passwords that remote subcommands require,
use the --passwordfile option, or specify
the password at the command prompt. You are always prompted for the administration
user name and password.

There is no logout subcommand. If you want to log in to another domain,
invoke asadmin login with new values for --host and --port.

Example 3–3 Logging In To a Domain on a Remote Machine

This example logs into a domain located on another machine. Options
are specified before the login subcommand.

asadmin> --host foo --port 8282 login
Please enter the admin user name>admin Please enter the admin password>
Trying to authenticate for administration of server at host [foo] and port [8282] ...
Login information relevant to admin user name [admin]
for host [foo] and admin port [8282] stored at [/.asadminpass] successfully.
Make sure that this file remains protected. Information stored in this
file will be used by asadmin commands to manage associated domain.

Example 3–4 Logging In to a Domain on the Default Port of Localhost

This example logs into a domain on myhost on the
default port. Options are specified before the login subcommand.

asadmin> --host myhost login
Please enter the admin user name>admin Please enter the admin password>
Trying to authenticate for administration of server at host [myhost] and port [4848] ...
An entry for login exists for host [myhost] and port [4848], probably from
an earlier login operation.
Do you want to overwrite this entry (y/n)?y
Login information relevant to admin user name [admin] for host [myhost]
and admin port [4848] stored at [/home/joe/.asadminpass] successfully.
Make sure that this file remains protected. Information stored in this file will be used by
asadmin commands to manage associated domain.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help login at the command line. For additional information
about passwords, see Administering Passwords.

To Delete a Domain

Use the delete-domain subcommand to delete an existing
domain from a server. Only the root user or the operating system user who
is authorized to administer the domain can run this subcommand.

Starting and Stopping a Domain

To Start a Domain

When
you start a domain or server, the domain administration server (DAS) is started.
After startup, the DAS runs constantly, listening for and accepting requests.

If the domain directory is not specified, the domain in the default as-install/domains directory is started. If
there are two or more domains, the domain_name operand
must be specified. Each domain must be started separately.

Note –

For Microsoft Windows, you can use an alternate method to start
a domain. From the Windows Start menu, select the command for your distribution
of GlassFish Server:

If you are using the Full Platform, select Programs ->
Oracle GlassFish Server -> Start Admin Server.

Example 3–6 Starting a Domain

If there is only one domain, you can omit the domain
name. If you do not include the password, you might be prompted to supply
it.

Name of the domain started: [domain1] and its location:
[C:\prelude\v3_prelude_release\distributions\web\target\glassfish
domains\domain1].
Admin port for the domain: [4848].

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help start-domain at the command line.

To Stop a Domain

Stopping a domain or server shuts down its domain administration server
(DAS). When stopping a domain, the DAS stops accepting new connections and
then waits for all outstanding connections to complete. This shutdown process
takes a few seconds. While the domain is stopped, the Administration Console and most
of the asadmin subcommands cannot be used. This subcommand
is particularly useful in stopping a runaway server. For more controlled situations,
you can use the restart-domain(1) subcommand.

Note –

For Microsoft Windows, you can use
an alternate method to stop a domain. From the Start menu, select the command
for your distribution of GlassFish Server:

If you are using the Full Platform, select Programs ->
Oracle GlassFish Server -> Stop Admin Server.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help stop-domain at the command line.

To Restart a Domain

Use the restart-domain subcommand in remote mode
to restart the Domain Administration Server (DAS) of the specified host. When
restarting a domain, the DAS stops accepting new connections and then waits
for all outstanding connections to complete. This shutdown process takes a
few seconds. Until the domain has restarted, the Administration Console and most of
the asadmin subcommands cannot be used.

This subcommand is particularly useful for environments where the server
machine is secured and difficult to get to. With the right credentials, you
can restart the server from a remote location as well as from the same machine.

After the service is created, start the service by using the Windows
Services Manager or the Windows Services Wrapper.

For example,
to start the service for the default domain by using the Windows Services
Wrapper, type:

C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe start

Example 3–10 Creating a Service on a Windows System

This example creates a service for the default domain on a system that
is running Windows.

asadmin> create-service
Found the Windows Service and successfully uninstalled it.
The Windows Service was created successfully. It is ready to be started. Here are
the details:
ID of the service: domain1
Display Name of the service:domain1 GlassFish Server
Domain Directory: C:\glassfishv3\glassfish\domains\domain1
Configuration file for Windows Services Wrapper: C:\glassfishv3\glassfish\domains\
domain1\bin\domain1Service.xml
The service can be controlled using the Windows Services Manager or you can use the
Windows Services Wrapper instead:
Start Command: C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe start
Stop Command: C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe stop
Uninstall Command: C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe
uninstall
Install Command: C:\glassfishv3\glassfish\domains\domain1\bin\domain1Service.exe
install
This message is also available in a file named PlatformServices.log in the domain's
root directory
Command create-service executed successfully.

To Configure a Domain for Automatic Restart
on Oracle Solaris 10

On Oracle Solaris 10, you can use the asadmin create-service subcommand
to create an Oracle Solaris Service Management Facility (SMF) service that
restarts a DAS. The service grants to the
process the privileges of the user that runs the process. When you create
an SMF service, the default user is the superuser. If you require a different
user to run the process, specify the user in method_credential.

If your process is to bind to a privileged port of Oracle Solaris 10,
the process requires the net_privaddr privilege. The privileged
ports of the Oracle Solaris operating system have port numbers less than 1024.

To determine if a user has the net_privaddr privilege,
log in as that user and type the command ppriv -l | grep net_privaddr.

After you create and enable the SMF service, if the domain goes down,
SMF restarts it.

Before You Begin

To run the asadmin create-service subcommand, you
must have solaris.smf.* authorization. See the useradd and usermod man pages to find out how to set
the authorizations. You must also have write permission in the directory tree: /var/svc/manifest/application/SUNWappserver. Usually, the superuser
has both of these permissions. Additionally, Oracle Solaris 10 administration
commands such as svccfg, svcs, and auths must be available in the PATH.

If a particular GlassFish Server domain should not have default user privileges,
modify the manifest of the service and reimport the service.

After the service is created, enable the service by using the svacdm enable command.

For example:

svacdm enable /appserver/domains/domain1

Example 3–11 Creating a Service to Restart a Domain Automatically on Oracle Solaris
10

This example creates a service for the default domain on a system that
is running Oracle Solaris.

asadmin> create-service
The Service was created successfully. Here are the details:
Name of the service:application/GlassFish/domain1
Type of the service:Domain
Configuration location of the service:/home/gfuser/glassfish-installations
/glassfishv3/glassfish/domains
Manifest file location on the system:/var/svc/manifest/application
/GlassFish/domain1_home_gfuser_glassfish-installations_glassfishv3
_glassfish_domains/Domain-service-smf.xml.
You have created the service but you need to start it yourself.
Here are the most typical Solaris commands of interest:
* /usr/bin/svcs -a | grep domain1 // status
* /usr/sbin/svcadm enable domain1 // start
* /usr/sbin/svcadm disable domain1 // stop
* /usr/sbin/svccfg delete domain1 // uninstall
Command create-service executed successfully

See Also

As you administer your service, the following Oracle Solaris commands
are useful: auths, smf_security, svcadm, svccfg, rbac, useradd,
and usermod.

To Restart Automatically on Linux

To set up automatic restart on Linux, you edit the /etc/inittab file.
If you use /etc/rc.local, or your system’s equivalent,
place a line in /etc/rc.local that calls the desired asadmin subcommand.

The text must be on a single line. The first three letters are a unique
designator for the process and can be altered.

To Prevent Service Shutdown When a User
Logs Out on Windows

By default, the Java Virtual Machine (JVM) receives signals from Windows
that indicate that Windows is shutting down, or that a user is logging out
of Windows, which causes the system to shut itself down cleanly. This behavior
causes the GlassFish Server service to shut down. To prevent the service from
shutting down when a user logs out, you must set the -XrsJava VM option.

Add the following line to the section of the as-install\domains\domain-name\config\domain.xml file
that defines Java VM options:

<jvm-options>-Xrs</jvm-options>

If the GlassFish Server service is running, restart the service for
your changes to take effect.

For a valid JVM installation, locations are checked in the following
order:

domain.xml (java-home inside java-config)

asenv.conf (setting AS_JAVA="path
to java home")

If a legal JDK is not found, a fatal error occurs and the problem is
reported back to you.

If necessary, change the JVM machine attributes for the domain.

In particular, you might need to change the JAVA_HOME environment
variable. For example, to change the JAVA_HOME variable, type:

as-install/bin/asadmin set "server.java-config.java-home=path-to-java-home"

Chapter 4 Administering the Virtual Machine
for the Java Platform

This chapter provides procedures for administering the Virtual Machine
for the Java platform (Java Virtual Machine) or JVM machine) in the Oracle GlassFish Server 3.0.1 environment
by using the asadmin command-line utility.

Instructions for accomplishing these tasks by using the Administration Console are
contained in the Administration Console online help.

Administering JVM Options

The Java Virtual Machine is an interpretive computing engine responsible
for running the byte codes in a compiled Java program. The virtual machine
translates the Java byte codes into the native instructions of the host machine. GlassFish Server,
being a Java process, requires a virtual machine to run and support the Java
applications running on it. JVM settings are part of an GlassFish Server configuration.

To Create JVM Options

Use the create-jvm-options subcommand in remote mode
to create JVM options in the Java configuration or the profiler elements of
the domain.xml file. If JVM options are created for a profiler,
these options are used to record the settings that initiate the profiler.

Example 4–4 Deleting Multiple JVM Options

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help delete-jvm-options at the command line.

To Generate a JVM Report

Use the generate-jvm-report subcommand in remote
mode to generate a JVM report showing the threads (dump of a stack trace),
classes, memory, and loggers for a specified domain
administration server (DAS). You can generate the following types of reports:
summary (default), class, thread, log.

Administering the Profiler

To Create a Profiler

A server instance is tied to a particular profiler by the profiler element
in the Java configuration. If JVM options are created for a profiler, the
options are used to record the settings needed to activate a particular profiler.
Use the create-profiler subcommand in remote mode to create
the profiler element in the Java configuration.

Only one profiler can exist. If a profiler already exists, you receive
an error message that directs you to delete the existing profiler before creating
a new one.

Instructions for accomplishing these tasks by using the Administration Console are
contained in the Administration Console online help.

About Thread Pools

The Virtual Machine for the Java platform (Java
Virtual Machine) or JVM machine) can support many threads
of execution simultaneously. To help performance, GlassFish Server maintains
one or more thread pools. It is possible to assign specific thread pools to
connector modules, to network listeners, or to the Object Request Broker (ORB).

One thread pool can serve multiple connector modules and enterprise
beans. Request threads handle user requests for application
components. When GlassFish Server receives a request, it assigns the request
to a free thread from the thread pool. The thread executes the client's requests
and returns results. For example, if the request needs to use a system resource
that is currently busy, the thread waits until that resource is free before
allowing the request to use that resource.

Configuring Thread Pools

You can specify the minimum and maximum number of threads that are reserved
for requests from applications. The thread pool is dynamically adjusted between
these two values.

To Create a Thread Pool

Use the create-threadpool subcommand in remote mode
to create a thread pool.

The minimum thread pool size that is specified signals the server to
allocate at least that many threads in reserve for application requests. That
number is increased up to the maximum thread pool size that is specified.
Increasing the number of threads available to a process allows the process
to respond to more application requests simultaneously.

If one resource adapter or application occupies all the GlassFish Server threads,
thread starvation might occur. You can avoid this by dividing the GlassFish Server threads
into different thread pools.

Instructions for accomplishing some of these tasks by using the Administration Console are
contained in the Administration Console online help.

Invoking a Servlet by Alternate Means

You can call a servlet deployed to GlassFish Server by using a URL in a
browser or embedded as a link in an HTML or JSP file. The format of a servlet
invocation URL is as follows:

http://server:port/context-root/servlet-mapping?name=value

The following table describes each URL section.

Table 6–1 URL Fields for Servlets
Within an Application

URL element

Description

server:port

The IP address (or host name) and optional port number.

To access the default
web module for a virtual server,
specify only this URL section. You do not need to specify the context-root or servlet-name unless you also wish to
specify name-value parameters.

context-root

For an application, the context root is defined in the context-root element
of the application.xml, sun-application.xml,
or sun-web.xml file. For an individually deployed web module, the context root is specified during deployment.

For both applications and individually deployed web modules, the default context root is the name of the
WAR file minus the .war suffix.

servlet-mapping

The servlet-mapping as configured in the web.xml file.

?name=value...

Optional request parameters.

Example 6–1 Invoking a Servlet With a URL

In this example, localhost is the host name, MortPages is the context root, and calcMortgage is the
servlet mapping.

Example 6–2 Invoking a Servlet From Within a JSP File

To invoke a servlet from within a JSP file, you can use a relative path.
For example:

<jsp:forward page="TestServlet"/><jsp:include page="TestServlet"/>

Changing Log Output for a Servlet

ServletContext.log messages are sent to the server
log. By default, the System.out and System.err output
of servlets are sent to the server log. During startup, server log messages
are echoed to the System.err output. Also by default, there
is no Windows-only console for the System.err output.

You can change these defaults using the Administration Console Write to System
Log box. If this box is checked, System.out output is sent
to the server log. If it is unchecked, System.out output
is sent to the system default location only.

Defining Global Features for Web Applications

You can use the default-web.xml file to define features
such as filters and security constraints that apply to all web applications.

For example, directory listings
are disabled by default for added security. To enable directory listings in
your domain's default-web.xml file, search for the definition
of the servlet whose servlet-name is equal to default, and set the value of the init-param named listings to true. Then restart the server.

The mime-mapping elements in default-web.xml are global and inherited by all web applications. You can override
these mappings or define your own using mime-mapping elements
in your web application's web.xml file. For more information
about mime-mapping elements, see the Servlet specification.

You can use the Administration Console to edit the default-web.xml file,
or edit the file directly using the following steps.

To Use the default-web.xml File

Place the JAR file for the filter, security constraint, or other
feature in the domain-dir/lib directory.

Edit the domain-dir/config/default-web.xml file
to refer to the JAR file.

Redirecting a URL

You can specify that a request for an old URL be treated as a request
for a new URL. This is called redirecting a URL.

To specify a redirected URL for a virtual server, use the redirect_n property, where n is
a positive integer that allows specification of more than one. Each of these redirect_n properties is inherited by
all web applications deployed on the virtual server.

The value of each redirect_n property
has two components which can be specified in any order:

The first component, from, specifies the
prefix of the requested URI to match.

The second component, url-prefix, specifies
the new URL prefix to return to the client. The from prefix is replaced by
this URL prefix.

Example 6–3 Redirecting a URL

Administering mod_jk

The Apache Tomcat Connector mod_jk can be used to
connect the web container with web servers such as Apache HTTP Server. By
using mod_jk, which comes with GlassFish Server, you can front GlassFish Server with
Apache HTTP Server.

You can also use mod_jk directly at the JSP/servlet
engine for load balancing.

Supported versions of the software referred to in this section include
Apache HTTP Server 2.2.11 (UNIX), mod_ssl 2.2.11, OpenSSL
0.9.8a, and mod_jk 1.2.27.

To Enable mod_jk

You can front GlassFish Server with Apache HTTP Server by enabling the mod_jk protocol for one of GlassFish Server's network listeners, as
described in this procedure. A typical use for mod_jk would
be to have Apache HTTP Server handle requests for static resources, while
having requests for dynamic resources, such as servlets and JavaServer Pages (JSPs), forwarded to, and handled by the GlassFish Server back-end
instance.

When you use the jk-enabled attribute of the
network listener, you do not need to copy any additional JAR files into the /lib directory. You can also create JK connectors under different
virtual servers by using the network listener attribute jk-enabled.

See Also

To Load Balance Using mod_jk and GlassFish Server

Load balancing is the process of dividing the amount of work that a
computer has to do between two or more computers so that more work gets done
in the same amount of time. Load balancing can be configured with or without
security.

In order to support stickiness, the Apache mod_jk load
balancer relies on a jvmRoute system property that is included
in any JSESSIONID received by the load balancer. This means
that every GlassFish Server instance that is front-ended by the Apache load balancer
must be configured with a unique jvmRoute system property.

To Enable SSL Between the mod_jk Load
Balancer and the Browser

To activate security for mod_jk on GlassFish Server,
you must first generate a Secure Socket Layer (SSL) self-signed certificate
on the Apache HTTP Server with the mod_ssl module. The
tasks include generating a private key, a Certificate Signing Request (CSR),
a self-signed certificate, and configuring SSL-enabled virtual hosts.

Add the following directives in the httpd.conf file
under the /etc/apache2/conf.d directory:

# Should mod_jk send SSL information (default is On)
JkExtractSSL On
# What is the indicator for SSL (default is HTTPS)
JkHTTPSIndicator HTTPS
# What is the indicator for SSL session (default is SSL_SESSION_ID)
JkSESSIONIndicator SSL_SESSION_ID
# What is the indicator for client SSL cipher suit (default is SSL_CIPHER)
JkCIPHERIndicator SSL_CIPHER
# What is the indicator for the client SSL certificated? (default is SSL_CLIENT_CERT)
JkCERTSIndicator SSL_CLIENT_CERT

Instructions for accomplishing these tasks and also for editing properties
by using the Administration Console are contained in the Administration Console online help.

About Logging

Logging is the process by which GlassFish Server captures
information about events that occur during server operation, such as configuration
errors, security failures, or server malfunction. This data is recorded in
a log file, and is usually the first source of information when problems occur.
Analyzing the log files can help you to determine the health of the server.

Although application components can use the Apache Commons Logging Library
to record messages, the platform standard JSR 047 API is recommended for better
log configuration.

Log File

GlassFish Server log records are captured in the server log. The server
log is named server.log by default and is typically located
in domain-dir/logs. You can change the default name or
location of the server log by using the Administration Console.

In addition to the server log, the domain-dir/logs directory
contains the following additional logs:

HTTP service access logs, located in the /access subdirectory

Transaction service logs, located in the /tx subdirectory

When the server log reaches the specified size in bytes, the log is
rotated and renamed with a timestamp name to server.log_date, where date is the date
and time that the file was rotated. You can also rotate this log manually
by following instructions in Rotating the Server Log.

Message is the text of the log message.
For all GlassFish Server SEVERE and WARNING messages
and for many INFO messages, the message begins with a message
ID that consists of a module code and a numerical value. For example: CORE5004

Setting Log Levels

The log level determines the granularity of the
message that is logged, from error only (SEVERE) to detailed
debug (FINEST). The following values apply: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST. These
log levels are hierarchically inclusive, which means that if you set a particular
log level, such as INFO, the messages that have log levels above that level
(SEVERE and WARNING) are also included.
If you set the log level to the lowest level, FINEST, your
output will include all the messages in the file. The default setting is INFO.

There are two levels of log settings available: global and logger-specific.
If you have chosen a logger-specific setting that is different from the global
setting, the logger-specific setting takes precedence.

Setting the global log level is done by editing the logging.properties file. Logging levels for the individual modules are set by using
the asadmin subcommands as explained in this section

Setting Log Levels

Because setting log levels is a dynamic operation, you do not need to
restart GlassFish Server for changes to take effect.

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help list-logger-levels at the command line.

To Set the Global Log Level

The global log level specifies which kinds of
events are logged across all loggers. The default level for message output
to the console is INFO (which also includes SEVERE and WARNING messages).

You configure global logging by editing the logging.properties file.
The default logging.properties file is located in the
same directory as the domain.xml file, typically domain-dir/config. You can choose a different
file name by using the java.util.logging.config.file system
property to specify a file name. For example:

java -Djava.util.logging.config.file=myfile

The ConsoleHandler has a separate log level setting
that limits the messages that are displayed. For example:

In a text editor, find the ConsoleHandler log
level line and make your changes.

Save the file.

Example 7–2 Changing the Global Log Level for All Loggers

If you set the log level at the root level, you are setting the level
of all loggers. This example sets the log level for all loggers to INFO:

.level= INFO

To Set Module Logger Levels

A module log level specifies which kinds of events
are logged for a particular logger. The default level for message output to
the console is INFO (which also includes SEVERE and WARNING messages). The global log level is overridden by a module-specific
log level.

By default, the module log level is set to FINE.
The lines for the loggers might look like this (the modules are indicated
in bold):

See Also

You can also view the full syntax and options of the subcommand by typing asadmin help set-log-level at the command line.

Rotating the Server Log

Logs are rotated automatically based on settings in the logging.properties file. You can change these settings by using the Administration Console.

To Rotate a Log File Manually

You
can rotate the server log file manually by using the rotate-log subcommand
in remote mode. The server log in the default location is immediately moved
to a time-stamped file and a new server log is created.

Because log rotation is a dynamic operation, you do not need to restart GlassFish Server for
changes to take effect.

Viewing Log Information

By default, all logging information is captured in the server.log file, typically located in domain-dir/logs. You can view logging information by using the Log Viewer in the Administration Console.
Instructions for using the Administration Console logging functions are contained
in the Administration Console online help.

To view information that has been collected for a module, you can open
the server.log file in a text editor and search for the
module that you are interested in.

Chapter 8 Administering the Monitoring
Service

This chapter explains how to monitor the Oracle GlassFish Server 3.0.1 components
and services by using the asadmin command-line utility.
Instructions for configuring JConsole to monitor GlassFish Server resources are
also provided.

About Monitoring

Monitoring is the process of reviewing the statistics
of a system to improve performance or solve problems. The monitoring service
can track and display operational statistics, such as the number of requests
per second, the average response time, and the throughput. By monitoring the
state of various components and services deployed in GlassFish Server, you can
identify performance bottlenecks, predict failures, perform root cause analysis,
and ensure that everything is functioning as expected. Data gathered by monitoring
can also be useful in performance tuning and capacity planning.

For this release of GlassFish Server, monitoring is exposed in a modular
way so that many client modules can access and display the monitoring statistics.
These clients include the Administration Console, the asadmin utility,
AMX, and REST interfaces.

How the Monitoring Tree Structure Works

A monitorable object is a component, subcomponent,
or service that can be monitored. GlassFish Server uses a tree structure to track
monitorable objects. Because the tree is dynamic, the tree changes as GlassFish Server components
are added or removed.

In the tree, a monitorable object can have child objects (nodes) that
represent exactly what can be monitored for that object. All child objects
are addressed using the dot (.) character as a separator. These constructed
names are referred to as dotted names. Detailed information
on dotted names is available in the dotted-names(5ASC) help page.

The following command lists the monitorable child objects of the instance server:

Each object is represented by a dotted name. Dotted names can also address
specific attributes in monitorable objects. For example, the jvm object
has a memory attribute with a statistic called maxheapsize. The following dotted name addresses the attribute:

server.jvm.memory.maxheapsize

Although an object is monitorable, it is not necessarily being actively
monitored. For instructions on activating monitoring, see Configuring Monitoring.

Tree Structure of Monitorable Objects

Each monitorable object has a hierarchical tree structure. In the tree,
a replaceable such as *statistics represents the
name of the attribute that you can show statistics for.

An example dotted name under the connection-factories node
might be server.jms-service.connection-factories.connection-factory-1 which
shows all the statistics for this connection factory. For available statistics,
see JMS/Connector Service Statistics.

Web Tree Hierarchy

An example dotted name for the servlet node
might be server.web.servlet.activeservletsloadedcount.
For available statistics, see Web Module Common Statistics.

About Monitoring for Add-on Components

An add-on component typically generates statistics that GlassFish Server can
gather at runtime. Adding monitoring capabilities enables an add-on component
to provide statistics to GlassFish Server in the same way as components that
are supplied in the GlassFish Server distributions. As a result, you can use
the same administrative interfaces to monitor statistics from any installed GlassFish Server component,
regardless of the origin of the component.

Tools for Monitoring GlassFish Server

The following asadmin subcommands
are provided for monitoring the services and components of GlassFish Server:

The enable-monitoring, disable-monitoring, or the get and set subcommands
are used to turn monitoring on or off. For instructions, see Configuring Monitoring.

The monitor --type subcommand
is used to display basic data for a particular type of monitorable object.
For instructions, see Viewing Common Monitoring Data.

The get subcommand is used to display comprehensive
data, such as the attributes and values for a dotted name. The get subcommand
used with a wildcard parameter displays all available attributes for any monitorable
object. For additional information, see Guidelines for Using the list and get Subcommands for Monitoring.

Configuring Monitoring

By default, the monitoring service is enabled for GlassFish Server, but
monitoring for the individual modules is not. To enable monitoring for a module,
you change the monitoring level for that module to LOW or HIGH, You can choose
to leave monitoring OFF for objects that do not need to be monitored.

LOW. Simple statistics,
such as create count, byte count, and so on

HIGH. Simple statistics
plus method statistics, such as method count, duration, and so on

Viewing Common Monitoring Data

To View Common Monitoring Data

Use the --type option of the monitor subcommand to specify the object for which you want to display
data, such as httplistener, jvm, webmodule. If you use the monitor subcommand without specifying
a type, an error message is displayed.

Output from the subcommand is displayed continuously in a tabular format.
The --interval option can be used to display
output at a particular interval (the default is 30 seconds).

Before You Begin

A monitorable object must be configured for monitoring before you can
display data on the object. See To Enable Monitoring.

Common Monitoring Statistics

HTTP Listener Common Statistics

The statistics available for the httplistener type
are shown in the following table.

Table 8–1 HTTP Listener Common Monitoring Statistics

Statistic

Description

ec

Error count. Cumulative value of the error count

mt

Maximum time. Longest response time for a request; not a cumulative
value, but the largest response time from among the response times

pt

Processing time. Cumulative value of the times taken to process each
request, with processing time being the average of request processing times
over request

rc

Request count. Cumulative number of requests processed so far

JVM Common Statistics

The statistics available for the jvm type are shown
in the following table.

Table 8–2 JVM Common Monitoring Statistics

Statistic

Description

count

Amount of memory (in bytes) that is guaranteed to be available for use
by the JVM machine

high

Retained for compatibility with other releases

low

Retained for compatibility with other releases

max

The maximum amount of memory that can be used for memory management.

min

Initial amount of memory (in bytes) that the JVM machine requests from
the operating system for memory management during startup

UpTime

Number of milliseconds that the JVM machine has been running since it
was last started

Web Module Common Statistics

The statistics available for the webmodule type are
shown in the following table.

Table 8–3 Web Module Common Monitoring Statistics

Statistic

Description

ajlc

Number of active JavaServer Pages (JSP)
technology pages that are loaded

asc

Current active sessions

aslc

Number of active servlets that are loaded

ast

Total active sessions

mjlc

Maximum number of JSP pages that are loaded

mslc

Maximum number of servlets that are loaded

rst

Total rejected sessions

st

Total sessions

tjlc

Total number of JSP pages that are loaded

tslc

Total number of servlets that are loaded

Viewing Comprehensive Monitoring Data

By applying the list and get subcommands
against the tree structure using dotted names, you can display more comprehensive
monitoring data, such as a description of each of the statistics and its unit
of measurement.

Guidelines for Using the list and get Subcommands for Monitoring

The underlying assumptions for using the list and get subcommands with dotted names are:

A list subcommand that specifies a dotted
name that is not followed by a wildcard (*)
lists the current node’s immediate children. For example, the following
subcommand lists all immediate children belonging to the server node:

list --monitor server

A list subcommand that specifies a dotted
name followed by a wildcard of the form .* lists a hierarchical
tree of child nodes from the specified node. For example, the following subcommand
lists all children of the applications node, their subsequent
child nodes, and so on:

list --monitor server.applications.*

A list subcommand that specifies a dotted
name preceded or followed by a wildcard of the form *dottedname or dotted * name or dottedname * lists
all nodes and their children that match the regular expression created by
the specified matching pattern.

A get subcommand followed by a .* or
a * gets the set of attributes and their values that belong
to the node specified.

For example, the following table explains the output of the list and get subcommands used with the dotted name for the resources node.

Table 8–4 Example Resources
Level Dotted Names

Subcommand

Dotted Name

Output

list --monitor

server.resources

List of pool names.

list --monitor

server.resources.connection-pool1

No attributes, but a message saying “Use get subcommand
with the --monitor option to view this node’s attributes
and values.”

get --monitor

server.resources.connection-pool1.*

List of attributes and values corresponding to connection pool attributes.

To View Comprehensive Monitoring Data

Although the monitor subcommand is useful in many
situations, it does not offer the complete list of all monitorable objects.
To work with comprehensive data for an object type, use the list --monitor and the get --monitor subcommands followed by the
dotted name of a monitorable object.

Before You Begin

A monitorable object must be configured for monitoring before you can
display information about the object. See To Enable Monitoring if needed.

List the objects that are enabled for monitoring by using the list(1) subcommand.

For
example, the following subcommand lists all components and services that have
monitoring enabled for instance server.

Comprehensive Monitoring Statistics

You can get comprehensive monitoring statistics by forming a dotted
name that specifies the statistic you are looking for. For example, the following
dotted name will display the cumulative number of requests for the HTTP service
on virtual-server1:

server.http-service.virtual-server1.request.requestcount

The tables in the following sections list the statistics that are available
for each monitorable object:

EJB Method Statistics

The statistics available for EJB method invocations are listed in the
following table.

Table 8–7 EJB Method Monitoring
Statistics

Statistic

Data Type

Description

executiontime

CountStatistic

Time, in milliseconds, spent executing the method for the last successful/unsuccessful
attempt to run the operation. This is collected for stateless and stateful
session beans and entity beans if monitoring is enabled on the EJB container.

methodstatistic

TimeStatistic

Number of times an operation is called; the total time that is spent
during the invocation, and so on.

totalnumerrors

CountStatistic

Number of times the method execution resulted in an exception. This
is collected for stateless and stateful session beans and entity beans if
monitoring is enabled for the EJB container.

totalnumsuccess

CountStatistic

Number of times the method successfully executed. This is collected
for stateless and stateful session beans and entity beans if monitoring enabled
is true for EJB container.

EJB Pool Statistics

Use the following dotted name pattern for EJB pool statistics:

server.applications.appname.ejbmodulename.bean-pool.ejbname.statistic

The statistics available for EJB pools are listed in the following table.

Table 8–8 EJB Pool Monitoring
Statistics

Statistic

Data Type

Description

jmsmaxmessagesload

CountStatistic

The maximum number of messages to load into a JMS session at one time
for a message-driven bean to serve. Default is 1. Applies only to pools for
message driven beans.

numbeansinpool

RangeStatistic

Number of EJBs in the associated pool, providing information about how
the pool is changing.

numthreadswaiting

RangeStatistic

Number of threads waiting for free beans, giving an indication of possible
congestion of requests.

totalbeanscreated

CountStatistic

Number of beans created in associated pool since the gathering of data
started.

totalbeansdestroyed

CountStatistic

Number of beans destroyed from associated pool since the gathering of
data started.

Timer Statistics

Use the following dotted name pattern for timer statistics:

server.applications.appname.ejbmodulename.timers.ejbname.statistic

The statistics available for timers are listed in
the following table.

JVM Class Loading System Statistics

Use the following dotted name pattern for JVM class loading system statistics:

server.jvm.class-loading-system.statistic

With Java SE, additional monitoring information can be obtained from
the JVM. Set the monitoring level to LOW to enable the display of this additional
information. Set the monitoring level to HIGH to also view information pertaining
to each live thread in the system. More information about the additional monitoring
features for Java SE is available in Monitoring and Management for the Java Platform.

The statistics available for the connection manager in an ORB are listed
in the following table.

Table 8–28 ORB Monitoring Statistics
(Connection Manager)

Statistic

Data Type

Description

connectionsidle

CountStatistic

Total number of connections that are idle to the ORB

connectionsinuse

CountStatistic

Total number of connections in use to the ORB

totalconnections

BoundedRangeStatistic

Total number of connections to the ORB

Resource Statistics (Connection Pool)

By monitoring connection pool resources you can measure performance
and capture resource usage at runtime. Connections are expensive and frequently
cause performance bottlenecks in applications. It is important to monitor
how a connection pool is releasing and creating new connections and how many
threads are waiting to retrieve a connection from a particular pool.

Thread Pool Monitoring Statistics

The statistics available for the thread pool are shown in the following
table.

Table 8–33 Thread Pool Monitoring
Statistics

Statistic

Data Type

Description

averagetimeinqueue

BoundedRangeStatistic

Average amount of time (in milliseconds) a request waited in the queue
before being processed

averageworkcompletiontime

BoundedRangeStatistic

Average amount of time (in milliseconds) taken to complete an assignment

currentbusythreads

CountStatistic

Number of busy threads

currentnumberofthreads

BoundedRangeStatistic

Current number of request processing threads

numberofavailablethreads

CountStatistic

Number of available threads

numberofworkitemsinqueue

BoundedRangeStatistic

Current number of work items waiting in queue

totalworkitemsadded

CountStatistic

Total number of work items added to the work queue as of last sampling

JVM Statistics for Java SE-Thread Information

The statistics available for ThreadInfo in the JVM
in Java SE are shown in the following table.

Table 8–34 JVM Monitoring Statistics
for Java SE - Thread Info

Statistic

Data Type

Description

blockedcount

CountStatistic

Total number of times that the thread entered the BLOCKED state.

blockedtime

CountStatistic

Time elapsed (in milliseconds) since the thread entered the BLOCKED state. Returns -1 if thread contention monitoring is disabled.

lockname

StringStatistic

String representation of the monitor lock that the thread is blocked
to enter or waiting to be notified through the Object.wait method.

lockownerid

CountStatistic

ID of the thread that holds the monitor lock of an object on which this
thread is blocking.

lockownername

StringStatistic

Name of the thread that holds the monitor lock of the object this thread
is blocking on.

stacktrace

StringStatistic

Stack trace associated with this thread.

threadid

CountStatistic

ID of the thread.

threadname

StringStatistic

Name of the thread.

threadstate

StringStatistic

State of the thread.

waitedtime

CountStatistic

Elapsed time (in milliseconds) that the thread has been in a WAITING state. Returns -1 if thread contention monitoring is disabled.

waitedcount

CountStatistic

Total number of times the thread was in WAITING or TIMED_WAITING states.

Transaction Service Statistics

The transaction service allows the client to freeze the transaction
subsystem in order to roll back transactions and determine which transactions
are in process at the time of the freeze. The transaction service fits into
the tree of objects as shown in Transactions Service Tree Hierarchy.

Use the following dotted name pattern for transaction service statistics:

server.transaction-service.statistic

The statistics available for the transaction service are shown in the
following table.

Table 8–35 Transaction Service
Monitoring Statistics

Statistic

Data Type

Description

activecount

CountStatistic

Number of transactions currently active.

activeids

StringStatistic

The ID’s of the transactions that are currently active. Every
such transaction can be rolled back after freezing the transaction service.

Web Session Statistics

The available web session statistics are shown in the following table.

Table 8–40 Web Session Monitoring Statistics

Statistic

Data Type

Description

activatedsessionstotal

CountStatistic

Total number of activated sessions

activesessionscurrent

RangeStatistic

Number of currently active sessions

activesessionshigh

CountStatistic

Maximum number of concurrently active sessions

expiredsessionstotal

CountStatistic

Total number of expired sessions

passivatedsessionstotal

CountStatistic

Total number of passivated sessions

persistedsessionstotal

CountStatistic

Total number of persisted sessions

rejectedsessionstotal

CountStatistic

Total number of rejected sessions

sessionstotal

CountStatistic

Total number of sessions created

Configuring JConsole to View GlassFish Server Monitoring
Data

Java SE provides tools to connect to an MBean Server and view the MBeans
registered with the server. JConsole is one such popular JMX Connector Client
and is available as part of the standard Java SE distribution. When you configure
JConsole for use with GlassFish Server, GlassFish Server becomes the JMX Connector's
server end and JConsole becomes the JMX connector's client end.

To Connect JConsole to GlassFish Server

Java SE 6 enhances management and monitoring of the virtual machine
by including a Platform MBean Server and by including managed beans (MBeans)
to configure the virtual machine.

To view all MBeans, GlassFish Server provides a configuration of the standard
JMX connector server called System JMX Connector Server. As part of GlassFish Server startup,
an instance of this JMX Connector Server is started. Any compliant JMX connector
client can connect to the server using the JMX Connector Server.

By default, GlassFish Server is configured with a non-secure System JMX
Connector Server. If this is an issue, the JMX connector can be removed. However,
access can be restricted to a specific IP address (for example, the loopback
address) by setting address to locahost.

Instructions for accomplishing the tasks in this chapter by using the Administration Console are
contained in the Administration Console online help.

About Life Cycle Modules

Life cycle modules, also known as initialization
services, provide a means of running short or long duration Java-based tasks
within the GlassFish Server environment. These modules are automatically initiated
at server startup and are notified at various phases of the server life cycle.
Configured properties for a life cycle module are passed as properties during
server initialization.

All life cycle module classes and interfaces are in the as-install/glassfish/modules/glassfish-api.jar file.

A life cycle module listens for and performs its tasks in response to
the following GlassFish Server sequence of events:

Initialization. The server
reads the configuration, initializes built-in subsystems (such as security
and logging services), and creates the containers.

Startup. The server loads
and initializes deployed applications.

Ready. The server begins
servicing requests.

Shutdown. The server shuts
down the applications and stops.

Termination. The server
closes the containers, the built-in subsystems, and the server runtime environment.

About Add-On Components

GlassFish Server is designed to provide
its functionality in a modular form so that you can choose to include the
functionality that you need and leave out the functionality that is not needed. OSGi modules, also called bundles, provide add-on functionality
for your deployed GlassFish Server. As new add-on components are developed and
existing components are modified, you can extend and update GlassFish Server by
installing these components. You can add components during runtime, without
stopping the server. But you must stop the server before updating or removing
an installed component.

Preconfigured Repositories for GlassFish Server

Image Packaging System (IPS) tools for updating GlassFish Server software
obtain updates from repositories that contain the OSGi modules and other content
for GlassFish Server.

Oracle GlassFish Server and GlassFish Server Open Source Edition each have their
own set of repositories, as explained in the following sections:

Commercial, production quality versions of the core components and add-on
components of Oracle GlassFish Server

contrib.glassfish.sun.com

pkg.sun.com/glassfish/v3/contrib/

Additional add-on components that are contributed by Oracle partners

contrib.glassfish.org

pkg.glassfish.org/v3/contrib/

Additional add-on components that are contributed by the GlassFish community

dev.glassfish.sun.com

pkg.sun.com/glassfish/v3/dev/

Developmental, beta, and prerelease versions of the components in the pkg.sun.com/glassfish/v3/release/ repository

For Oracle GlassFish Server installations,
the release.glassfish.sun.com publisher is designated as
the preferred publisher. To ensure that installations
contain only commercial, production quality version of components by default,
the preferred publisher is treated specially by the tools for updating GlassFish Server software:

If an add-on component is available from the preferred publisher and
from other publishers, the Update Tool GUI and the pkg CLI
list and install the component from the preferred publisher.

After a component has been installed from the preferred publisher, the
Update Tool, Software Update, and desktop notifier GUIs search for updates
to that component only from the preferred publisher.

If you have support for Oracle GlassFish Server, you can acquire an
SSL certificate and key to change the preferred publisher's repository URL
from pkg.sun.com/glassfish/v3/release/ to pkg.sun.com/glassfish/v3/support/. This repository provides more frequent commercial, production
quality updates. For more information, see the pkg.sun.com Certificate Generator.

The pkg Command

The pkg command is the command-line equivalent to
Update Tool. Most of the tasks that can be performed with the graphical Update
Tool can be performed from a command line using the pkg tool.

The pkg command is located in the as-install-parent/bin directory. To run the pkg command without specifying the path, ensure that this directory
is in your path.

The pkg command enables you to create update
scripts and to update software on headless systems. A headless system does
not have a monitor, graphics card, or keyboard.

Most of the procedures in this chapter are based on the pkg command.
A set of reference pages that contain details about using the pkg command
is included with GlassFish Serverin the as-install-parent/pkg/man directory.

Administration Console

The Administration Console enables you to perform the following tasks that are
related to extending and updating GlassFish Server:

Installing add-on components

Viewing available updates to installed components

Viewing installed components

For more information, see the Administration Console online help.

Note –

The Administration Console does not enable you to
update or remove installed components. Instead, you must stop the GlassFish Server domain
and use Update Tool or the pkg command.

Adding Components

This section provides instructions for using the pkg command
to install GlassFish Server add-on components on your deployed GlassFish Server.

To Install an Add-on Component

The pkg command enables you to install an add-on component on your system.
If multiple versions of a package are available, the latest one is applied
unless you specify otherwise. The pkg command, located
in the as-install-parent/bin directory,

Note –

If the pkg component, the updatetool component,
or any other valid component that you try to invoke from the command line
is not yet installed on your deployed GlassFish Server, you will receive a query
asking if you want to install the component. Answer Y to install the component.

Updating Installed Components

To Update an Installed Component

When you install an updated version of a component, only those files
that have been modified are downloaded and installed. Files that have been
removed in the updated package are removed during the update process.

See Also

For the full syntax and options of the pkg command,
see the pkg(1) man page. This man page is installed only after the pkg utilities
have been fully installed.

To view this man page on UNIX and Linux systems, type the following
command in a terminal window:

man -M as-install-parent/pkg/man/
pkg

To view this man page on Windows systems, use
the type command to view the file as-install-parent\pkg\man\cat1\pkg.1.

To Update All Installed Components in an
Image

GlassFish Server enables you to maintain multiple installation images on
a single system. When you update an installation image, all the components
that are present in that image are updated to new versions, if new versions
are available. When you install updated versions of components, only those
files that have been modified are downloaded and installed. Files that have
been removed in the updated package are removed during the update process.

See Also

For the full syntax and options of the pkg command,
see the pkg(1) man page. This man page is installed only after the pkg utilities
have been fully installed.

To view this man page on UNIX and Linux systems, type the following
command in a terminal window:

man -M as-install-parent/pkg/man/
pkg

To view this man page on Windows systems, use
the type command to view the file as-install-parent\pkg\man\cat1\pkg.1.

Removing Installed Components

If you are discontinuing use of a component and want to remove it from
your system, you can do this by using the uninstall command.
If you need to revert to a prior version of a component, you will need to
uninstall the current version and install the prior version by specifying
the version number.

See Also

For the full syntax and options of the pkg command,
see the pkg(1) man page. This man page is installed only after the pkg utilities
have been fully installed.

To view this man page on UNIX and Linux systems, type the following
command in a terminal window:

man -M as-install-parent/pkg/man/
pkg

To view this man page on Windows systems, use
the type command to view the file as-install-parent\pkg\man\cat1\pkg.1.

To Uninstall and Revert to an Older Version
of a Component

If there is a malfunction in an installed component, you might want
to revert to an older version of that component. The way to restore an older
version of a component is to first uninstall the current version of the component,
then install the specific older version that you want to reinstate.

Before You Begin

Be sure to verify that the older version of the component is in the
repository before you uninstall your current version.

Oracle provides software support only for Oracle GlassFish Server,
not for GlassFish Server Open Source Edition. Additionally, some features of Oracle GlassFish Server are
not available in GlassFish Server Open Source Edition.

If you are using GlassFish Server Open Source Edition, you can upgrade to Oracle GlassFish Server by purchasing a right-to-use and installing the add-on component
for upgrading GlassFish Server Open Source Edition. To obtain this component, and to ensure
the reliability of your upgraded installation, you must configure your GlassFish Server installation
to obtain updates from the appropriate repositories.

Note –

To use Oracle GlassFish Server in production after the upgrade,
you must obtain a right to use this software from Oracle.

You can upgrade to Oracle GlassFish Server by using either Update Tool or
the pkg command.

To Upgrade to Oracle GlassFish Server by Using
Update Tool

The procedure explains how to use Update Tool to obtain and install
the add-on component for upgrading GlassFish Server Open Source Edition to Oracle GlassFish Server.
For general instructions for using Update Tool, see the Update Tool online
help.

Before You Begin

Ensure that GlassFish Server Open Source Edition 3.0.1 is installed on your machine.

See Also

For the full syntax and options of the pkg command,
see the pkg(1) man page. This man page is installed only after the pkg utilities
have been fully installed.

To view this man page on UNIX and Linux systems, type the following
command in a terminal window:

man -M as-install-parent/pkg/man/
pkg

To view this man page on Windows systems, use
the type command to view the file as-install-parent\pkg\man\cat1\pkg.1.

Extending and Updating GlassFish Server Inside
a Closed Network

GlassFish Server might be installed on a machine without an Internet connection.
For example, for security reasons, GlassFish Server might be installed behind
a restrictive firewall, or it might be installed on a LAN that is physically
isolated from other networks. In such situations, neither the graphical Update Tool nor
the pkg command-line utility that are included with GlassFish Server can
contact a public repository server to download and install updates. Therefore,
a local repository server must be configured inside the closed network and
the GlassFish Server updates installed from there.

The GlassFish Server updates inside the closed network are
performed normally, but use the local repository server instead of the public
repository servers.

To Install the Pre-Installed Toolkit Image
Inside a Closed Network

The Pre-Installed Toolkit Image provides the software components that
are required to configure and run a local repository server inside a closed
network. Running a local repository server makes it possible for a GlassFish Server installation
to obtain packages and updates from within the closed network rather than
from the default public GlassFish Server repositories.

Before You Begin

The first three steps of this procedure require access to
a machine that is connected to the Internet. This machine must also be able
to write to some type of removable medium, such as CD, DVD, USB drive, or
flash memory card.

The remaining steps in the procedure are performed on the
machines that are inside the closed network, and do not require access to
an Internet connection.

To Install Updates From a Local Repository

After configuring a GlassFish Server installation to use a local repository
server, as described in the previous procedures in this section, GlassFish Server updates
inside a closed network are performed normally. The only difference is that
the GlassFish Server installation being updated inside the closed network will
use a local repository server instead of the public repository servers.

Perform the following procedure on each GlassFish Server installation that
will be updated.