Sun GlassFish Enterprise Server v3 Administration Guide

Part I Runtime Administration

Chapter 2 General Administration

This chapter provides instructions for performing general administration tasks in the Sun GlassFish^TM Enterprise Server v3 environment by using the asadmin command-line utility.

The following topics are addressed here:

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

Using the `asadmin` Utility

Use the asadmin utility to perform administrative tasks for Sun GlassFish Enterprise Server from the command line or from a script. You can use this utility instead of the Administration Console interface.

The following topics are addressed here:

Path to the `asadmin` Utility

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

`asadmin` Utility Syntax

The syntax for running the asadmin utility is as follows:

asadmin [asadmin-util-options] [subcommand [subcommand-options] [operands]]

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.

For a list of the subcommands for this release of Enterprise Server, see Section 1 of Sun GlassFish Enterprise Server v3 Reference Manual.

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

Note –
Not all subcommand options are supported for this release of Enterprise 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.

asadmin list-applications
hello <web>
Command list-applications executed successfully.

Example 2–2 Specifying an `asadmin` Utility Option With a Subcommand in Single Mode

This example specifies the --host asadmin utility option with the list-applications subcommand in single mode. In this example, the DAS is running on the host srvr1.example.com.

The example shows that the applications basic-ezcomp, scrumtoys, ejb31-war, and automatic-timer-ejb are deployed on the host srvr1.example.com.

asadmin --host srvr1.example.com list-applications
basic-ezcomp <web>
scrumtoys <web>
ejb31-war <ejb, web>
automatic-timer-ejb <ejb>
Command list-applications executed successfully.

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

This example specifies the --host asadmin 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.

asadmin --host srvr1.example.com list-applications --type web
basic-ezcomp <web>
scrumtoys <web>
ejb31-war <ejb, web>
Command list-applications executed successfully.

To Display Help Information for the `asadmin` Utility or a Subcommand

Enterprise 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 Sun GlassFish Enterprise Server v3 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

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.

Note –

Starting a multimode session does not require a running DAS.

Do one of the following:
- Run the asadmin utility without a subcommand.
- Use the multimode(1) subcommand.
If necessary, also specify any asadmin utility options that will apply throughout the multimode session.

In a multimode session, the asadmin> prompt is displayed on the command line. You can now type asadmin subcommands at this prompt to administer Enterprise Server.

Example 2–6 Starting a Multimode Session With `asadmin` Utility Options

This example starts a multimode session in which the asadmin utility options --user and --passwordfile are set for the session.

asadmin --user admin1 --passwordfile pwd.txt multimode

Example 2–7 Starting a Multimode Session by Using the `multimode` Subcommand

This example uses the multimode subcommand to start a multimode session in which the default asadmin utility options are used.

asadmin multimode

The asadmin> prompt is displayed on the command line.

Example 2–8 Running a Subcommand in a Multimode Session

This example starts a multimode session and runs the list-domains subcommand in the session.

asadmin
Enter commands one per "line", ^D to quit
asadmin> list-domains
Name: domain1 Status: Running
Command list-domains executed successfully.
asadmin>

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.

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:

Creating the domain customdomain
Starting the domain customdomain
Listing all available subcommands
Stopping the domain customdomain
Deleting the domain customdomain

The content of the commands_file.txt file is as follows:

create-domain --portbase 9000 customdomain
start-domain customdomain
list-commands
stop-domain customdomain
delete-domain customdomain

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 --port asadmin utility option must also be set.

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

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.

The following topics are addressed here:

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.

Ensure that the server is running.

Remote subcommands require a running server.

Create system properties by using the create-system-properties(1) subcommand.

Information about properties for the subcommand is included in this help page.

Example 2–10 Creating a System Property

This example creates a system property associated with http-listener-port=1088 on localhost.

asadmin> create-system-properties http-listener-port=1088
Command create-system-properties executed successfully.

To List System Properties

Use the list-system-properties subcommand in remote mode to list the system properties that apply to a domain or configuration.

Ensure that the server is running.

Remote subcommands require a running server.

List system properties by using the list-system-properties(1) subcommand.

The existing system properties are displayed, including predefined properties such as HTTP_LISTENER_PORT and HTTP_SSL_LISTENER_PORT.

Example 2–11 Listing System Properties

This example lists the system properties on host localhost.

asadmin> list-system-properties
http-listener-port=1088
Command list-system-properties executed successfully.

To Delete a System Property

Use the delete-system-property subcommand in remote mode to delete system properties.

Ensure that the server is running.

Remote subcommands require a running server.

List the existing system properties by using the list-system-properties(1) subcommand.

Delete the system property by using the delete-system-property(1) subcommand.

If necessary, notify users that the system property has been deleted.

Example 2–12 Deleting a System Property

This example deletes a system property named http-listener-port from localhost.

asadmin> delete-system-property http-listener-port
Command delete-system-property executed successfully.

Administering Resources

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

The following topics are addressed here:

To Add Resources From an XML File

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.

Ensure that the server is running.

Remote subcommands require a running server.

Add resources from an XML file by using the add-resources(1) subcommand.

Information about properties for the subcommand is included in this help page.

Restart Enterprise Server.

See To Restart a Domain.

Example 2–13 Adding Resources

This example creates resources using the contents of the resource.xml file on localhost.

asadmin> add-resources c:\tmp\resource.xml
Command : JDBC resource jdbc1 created successfully.
Command : JDBC connection pool poolA created successfully.
Command add-resources executed successfully.

Listing Various System Elements

To Display the Enterprise Server Version

Use the version subcommand in remote mode to display information about the Enterprise 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.

Ensure that the server is running.

Remote subcommands require a running server.

Display the version by using the version(1) subcommand.

Example 2–14 Displaying Version Information

This example displays the version of Enterprise Server on the local host.

asadmin> version
Version = GlassFish v3
Command version executed successfully.

To List Applications

Use the list-applications subcommand in remote mode to list the deployed Java^TM applications. If the --type option is not specified, all applications are listed.

Ensure that the server is running.

Remote subcommands require a running server.

List applications by using the list-applications(1) subcommand.

Example 2–15 Listing Applications

This example lists the web applications on localhost.

asadmin> list-applications --type web
hellojsp <web>
Command list-applications executed successfully.

To List Containers

Use the list-containers subcommand in remote mode to list application containers.

Ensure that the server is running.

Remote subcommands require a running server.

List containers by using the list-containers(1) subcommand.

Example 2–16 Listing Containers

This example lists the containers on localhost.

asadmin> list-containers
List all known application containers
Container : grizzly
Container : ejb
Container : webservices
Container : ear
Container : appclient
Container : connector
Container : jpa
Container : web
Container : jruby
Container : security
Container : webbeans
Command list-containers executed successfully.

To List Modules

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

Ensure that the server is running.

Remote subcommands require a running server.

List modules by using the list-modules(1) subcommand.

Example 2–17 Listing Modules

This example lists the accessible modules.

asadmin> list-modules

Information similar to the following is displayed (partial output):

List Of Modules
Module : org.glassfish.web.jstl-connector:10.0.0.b28
    properties=(visibility=public,State=READY,Sticky=true)
    Module Characteristics : List of Jars implementing the module
        Jar : file:/C:/Preview/v3_Preview_release/distributions/web/target/glass
fish/modules/web/jstl-connector.jar
    Module Characteristics : List of imported modules
    Module Characteristics : Provides to following services
Module : org.glassfish.admingui.console-common:10.0.0.b28
    properties=(visibility=public,State=NEW,Sticky=true)
Module : org.glassfish.admin.launcher:10.0.0.b28
    properties=(visibility=public,State=NEW,Sticky=true)
Module : org.glassfish.external.commons-codec-repackaged:10.0.0.b28
    properties=(visibility=public,State=NEW,Sticky=true)
Module : com.sun.enterprise.tiger-types-osgi:0.3.32.Preview-b28
    properties=(visibility=public,State=READY,Sticky=true)
    Module Characteristics : List of imported modules
    Module Characteristics : Provides to following services
    Module Characteristics : List of Jars implementing the module
        Jar : file:/C:/Preview/v3_Preview_release/distributions/web/target/glass
fish/modules/tiger-types-osgi.jar.
...
Command list-modules executed successfully.

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.

Ensure that the server is running.

Remote subcommands require a running server.

List subcommands by using the list-commands(1) subcommand.

Example 2–18 Listing Subcommands

This example lists only local subcommands.

asadmin> list-commands --localonly
create-domain
delete-domain
list-commands
list-domains
login
monitor
start-database
start-domain
stop-domain
stop-database
version
Command list-commands executed successfully.

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.

Ensure that the server is running.

Remote subcommands require a running server.

List timers by using thelist-timers(1) subcommand.

Example 2–19 Listing Timers

This example lists the timers in a particular standalone server instance. There is one currently active timer set.

asadmin> list-timers server
1
The list-timers command was executed successfully.

To Show Component Status

Use the show-component-status subcommand in remote mode to get the status (either enabled or disabled) of the specified deployed component.

Ensure that the server is running.

Remote subcommands require a running server.

Show component status by using the show-component-status(1) subcommand.

Example 2–20 Showing Status of a Component

This example shows the status of the MEjbApp component.

asadmin> show-component-status MEjbApp
Status of MEjbApp is enabled
Command show-component-status executed successfully.

Using REST Interfaces to Administer Enterprise Server

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

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

Web browsers
cURL
GNU Wget

You can also use the Enterprise Server REST interfaces in REST client applications that are developed in languages such as:

JavaScript
Ruby
Perl
Java
JavaFX

The implementation of the Enterprise Server REST interfaces is based on project Jersey. Project Jersey is the reference implementation of Java ^TM Specification Request (JSR) 311: JAX-RS: The Java API for RESTful Web Services. Information about JSR 311 is also available from the JSR 311 project home page.

The following topics are addressed here:

Using REST URLs to Administer Enterprise 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 Enterprise 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 Enterprise 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

Screen capture showing the web page for the REST resource
for managing a domain.

Using REST Resource Methods to Administer Enterprise Server

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

Table 2–1 REST Resource Methods for Administering Monitoring and Configuration Data


Task	REST Method
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.

You can specify the format in which this information is presented. For more information, see Formats for Resource Representation.

Ensure that the server is running.

Operations on REST resources for Enterprise Server data require a running server.

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.

curl -X OPTIONS -H "Accept: application/json" http://localhost:4848/management/domain
{"Domain":
  {
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "log-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "application-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "locale":{"Key":"false", "Type":"string", "Optional":"true"},
        "version":{"Key":"false", "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    }
  }
}

To Retrieve Data for a Node in the Tree

Retrieving data for a node in the tree obtains the following information about the REST resource that represents the node:

A list of the REST methods that the resource supports
A list of the attributes of the resource and their values
A list of URLs to the children of the resource

You can specify the format in which this information is presented. For more information, see Formats for Resource Representation.

Ensure that the server is running.

Operations on REST resources for Enterprise Server data require a running server.

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

Example 2–22 Retrieving Data for a Node in the Tree

This example uses the cURL utility to retrieve data for the resource for a domain. The example uses the following options of the cURL utility:

-X to specify that the GET 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.

Line breaks are added to enhance readability.

curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain
{

  "Domain":{"log-root":"${com.sun.aas.instanceRoot}/logs", 
"application-root":"${com.sun.aas.instanceRoot}/applications", 
"locale":"", "version":"74.1"},

  "Methods":{
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "log-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "application-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "locale":{"Key":"false", "Type":"string", "Optional":"true"},
        "version":{"Key":"false", "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    }
  },

  "Child Resources":[
    "http://localhost:4848/management/domain/configs",
    "http://localhost:4848/management/domain/resources",
    "http://localhost:4848/management/domain/servers",
    "http://localhost:4848/management/domain/property",
    "http://localhost:4848/management/domain/applications",
    "http://localhost:4848/management/domain/system-applications",
    "http://localhost:4848/management/domain/stop",
    "http://localhost:4848/management/domain/restart",
    "http://localhost:4848/management/domain/uptime",
    "http://localhost:4848/management/domain/version",
    "http://localhost:4848/management/domain/rotate-log",
    "http://localhost:4848/management/domain/host-port"
  ]

To Add a Node to the Tree

Ensure that the server is running.

Operations on REST resources for Enterprise Server data require a running server.

Determine the acceptable message parameters for the POST method of the resource that represents the parent of the node.

For information about how to perform this step, see To Determine the Methods and Method Parameters That a Node in the Tree Supports.

Use the POST method on the REST resource that represents the parent of the node that you are adding.

Confirm that the node has been added.

Perform this step on the resource that represents the node that you have just added, not the parent. For information about how to perform this step, see To Retrieve Data for a Node in the Tree.

Example 2–23 Adding a Node to the Tree

This example uses the cURL utility to add a JDBC resource node to the tree by creating a REST resource to represent the JDBC resource.

In this example, the DAS is running on the local host and the HTTP port for administration is 4848.

Line breaks are added to enhance readability.

This step determines the acceptable message parameters for the POST method of the resource jdbc-resource.

curl -X OPTIONS -H "Accept: application/json" 
http://localhost:4848/management/domain/resources/jdbc-resource
{"JdbcResource":
  {
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "id":{"Acceptable Values":"", "Default Value":"", "Type":"string", 
            "Optional":"false"},
        "enabled":{"Acceptable Values":"", "Default Value":"true", 
            "Type":"boolean", "Optional":"true"},
        "description":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"true"},
        "target":{"Acceptable Values":"", "Default Value":"", "Type":"string", 
            "Optional":"true"},
        "property":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"true"},
        "connectionpoolid":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"false"}
      }
    },
    "Method":{
      "Name":"GET"
    }
  }
}

This step adds a resource as a child of the jdbc-resource resource. The -d option of the cURL utility sets the required message parameters as follows:

id is set to jdbc/myjdbcresource.
connectionpoolid is set to DerbyPool.

curl -X POST -d "id=jdbc/myjdbcresource&connectionpoolid=DerbyPool" 
http://localhost:4848/management/domain/resources/jdbc-resource
"http://localhost:4848/management/domain/resources/jdbc-resource/
jdbc/myjdbcresource" created successfully.

This step confirms that the node has been added by retrieving data for the REST resource that represents the node.

curl -X GET -H "Accept: application/json" 
http://localhost:4848/management/domain/resources/
jdbc-resource/jdbc-myjdbcresource
{

  "JdbcMyjdbcresource":{"enabled":"true", "pool-name":"DerbyPool", 
      "description":"", "jndi-name":"jdbc/myjdbcresource", "object-type":"user"},

  "Methods":{
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "enabled":{"Key":"false", "Default Value":"true", 
            "Type":"boolean", "Optional":"true"},
        "pool-name":{"Key":"false", "Type":"string", "Optional":"true"},
        "description":{"Key":"false", "Type":"string", "Optional":"true"},
        "jndi-name":{"Key":"true", "Type":"string", "Optional":"true"},
        "object-type":{"Key":"false", "Default Value":"user", 
            "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    },
    "Method":{
      "Name":"DELETE",
      "Message Parameters":{
        "target":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"true"}
      }
    }
  }

}

To Update a Node in the Tree

Ensure that the server is running.

Operations on REST resources for Enterprise Server data require a running server.

Determine the acceptable message parameters for the POST method of the resource that represents the node.

For information about how to perform this step, see To Determine the Methods and Method Parameters That a Node in the Tree Supports.

Use the POST method on the REST resource that represents the node that you are updating.

Confirm that the node has been updated.

For information about how to perform this step, see To Retrieve Data for a Node in the Tree.

Example 2–24 Updating a Node in the Tree

This example uses the cURL utility to update a JDBC resource in the tree by modifying the REST resource that represents the JDBC resource.

In this example, the DAS is running on the local host and the HTTP port for administration is 4848.

Line breaks are added to enhance readability.

This step determines the acceptable message parameters for the POST method of the resource jdbc-myjdbcresource.

curl -X OPTIONS -H "Accept: application/json" 
http://localhost:4848/management/domain/resources/
jdbc-resource/jdbc-myjdbcresource
{"JdbcMyjdbcresource":
  {
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "enabled":{"Key":"false", "Default Value":"true", 
            "Type":"boolean", "Optional":"true"},
        "pool-name":{"Key":"false", "Type":"string", "Optional":"true"},
        "description":{"Key":"false", "Type":"string", "Optional":"true"},
        "jndi-name":{"Key":"true", "Type":"string", "Optional":"true"},
        "object-type":{"Key":"false", "Default Value":"user", 
            "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    },
    "Method":{
      "Name":"DELETE",
      "Message Parameters":{
        "target":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"true"}
      }
    }
  }
}

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.

curl -X POST -d "enabled=false" 
http://localhost:4848/management/domain/resources/
jdbc-resource/jdbc-myjdbcresource
"http://localhost:4848/management/domain/resources/jdbc-resource/
jdbc-myjdbcresource" updated successfully.

This step confirms that the node has been updated by retrieving data for the REST resource that represents the node.

curl -X GET -H "Accept: application/json" 
http://localhost:4848/management/domain/resources/
jdbc-resource/jdbc-myjdbcresource
{

  "JdbcMyjdbcresource":{"enabled":"false", "pool-name":"DerbyPool", 
       "description":"", "jndi-name":"jdbc/myjdbcresource", "object-type":"user"},

  "Methods":{
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "enabled":{"Key":"false", "Default Value":"true", 
            "Type":"boolean", "Optional":"true"},
        "pool-name":{"Key":"false", "Type":"string", "Optional":"true"},
        "description":{"Key":"false", "Type":"string", "Optional":"true"},
        "jndi-name":{"Key":"true", "Type":"string", "Optional":"true"},
        "object-type":{"Key":"false", "Default Value":"user", 
            "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    },
    "Method":{
      "Name":"DELETE",
      "Message Parameters":{
        "target":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"true"}
      }
    }
  }

}

To Delete a Node From the Tree

Ensure that the server is running.

Operations on REST resources for Enterprise Server data require a running server.

Confirm that the node can be deleted.

For information about how to perform this step, see To Determine the Methods and Method Parameters That a Node in the Tree Supports.

Confirm that the node has been deleted.

Perform this step on the resource that represents the parent of the node that you have just deleted. For information about how to perform this step, see To Retrieve Data for a Node in the Tree.

Example 2–25 Deleting a Node From the Tree

This example uses the cURL utility to delete a JDBC resource from the tree by deleting the REST resource that represents the JDBC resource.

In this example, the DAS is running on the local host and the HTTP port for administration is 4848.

Line breaks are added to enhance readability.

This step confirms that the node can be deleted by retrieving the REST methods that the resource jdbc-myjdbcresource supports.

curl -X OPTIONS -H "Accept: application/json" 
http://localhost:4848/management/domain/resources/
jdbc-resource/jdbc-myjdbcresource
{"JdbcMyjdbcresource":
  {
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "enabled":{"Key":"false", "Default Value":"true", 
            "Type":"boolean", "Optional":"true"},
        "pool-name":{"Key":"false", "Type":"string", "Optional":"true"},
        "description":{"Key":"false", "Type":"string", "Optional":"true"},
        "jndi-name":{"Key":"true", "Type":"string", "Optional":"true"},
        "object-type":{"Key":"false", "Default Value":"user", 
            "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    },
    "Method":{
      "Name":"DELETE",
      "Message Parameters":{
        "target":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"true"}
      }
    }
  }
}

This step deletes the jdbc-myjdbcresource resource.

curl -X DELETE http://localhost:4848/management/domain/resources/
jdbc-resource/jdbc-myjdbcresource

This step confirms that the node has been deleted by retrieving data for the REST resource that represents the parent of the node.

curl -X GET -H "Accept: application/json" 
http://localhost:4848/management/domain/resources/jdbc-resource/
{

  "JdbcResource":{},

  "Methods":{
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "id":{"Acceptable Values":"", "Default Value":"", "Type":"string", 
            "Optional":"false"},
        "enabled":{"Acceptable Values":"", "Default Value":"true", 
            "Type":"boolean", "Optional":"true"},
        "description":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"true"},
        "target":{"Acceptable Values":"", "Default Value":"", "Type":"string", 
            "Optional":"true"},
        "property":{"Acceptable Values":"", "Default Value":"", "Type":"string",
            "Optional":"true"},
        "connectionpoolid":{"Acceptable Values":"", "Default Value":"", 
            "Type":"string", "Optional":"false"}
      }
    },
    "Method":{
      "Name":"GET"
    }
  },

  "Child Resources":[
    "http://localhost:4848/management/domain/resources/jdbc-resource/
        jdbc-__TimerPool",
    "http://localhost:4848/management/domain/resources/jdbc-resource/
        jdbc-__default"
  ]

Child Resources for Non-CRUD Operations

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

Securing Enterprise Server REST Interfaces

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

Securing Enterprise Server REST Interfaces involves the following sequence of tasks:

Adding an admin-realm user to the asadmin user group
Enabling Secure Sockets Layer (SSL)

For information about how to perform these tasks from the command line, see the following documentation:

For information about how to perform these tasks by using the Administration Console, see the following topics in the Administration Console online help:

To Add a User to the Admin Realm
To Edit SSL Settings for a Protocol

Formats for Resource Representation

The Enterprise Server REST interfaces represent resources in the following formats:

JSON
XML
HTML

How to specify the resource representation depends on how you are accessing the Enterprise 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:

{
    "resource":{attributes},

    "Methods": {
        method-list
    }

    "Child Resources":[urls]
}

The replaceable items in this format are as follows:

resource: The name of the resource.
attributes: Zero or more name-value pairs separated by a comma (,). Each name-value pair is specified as "name":value.
method-list: One or more metadata sets separated by a comma (,) that represent the methods that the resource supports. For the format of each metadata set, see JSON Representation of a Method in a Method List.
urls: Zero or more URLs to child resources separated by a comma (,).

JSON Representation of a Method in a Method List

The JSON representation of a method in a method list is as follows:

Method":{
    "Name":"method-name",

    "Message Parameters":{
        message-parameter-list
    }

    "Query Parameters":{
        queryparameter- list
    }
}

The replaceable items in this format are as follows:

method-name: The name of the method, which is GET, POST, or DELETE.
message-parameter-list: Zero or more metadata sets separated by a comma (,) that represent the message parameters that are allowed for the method. For the format of each metadata set, see JSON Representation of a Message Parameter or a Query Parameter.
query-parameter-list: Zero or more metadata sets separated by a comma (,) that represent the query parameters that are allowed for the method. For the format of each metadata set, see JSON Representation of a Message Parameter or a Query Parameter.

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.

Line breaks are added to enhance readability.

{

  "Domain":{"log-root":"${com.sun.aas.instanceRoot}/logs", 
       "application-root":"${com.sun.aas.instanceRoot}/applications", 
       "locale":"", "version":"73"},

  "Methods":{
    "Method":{
      "Name":"POST",
      "Message Parameters":{
        "log-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "application-root":{"Key":"false", "Type":"string", "Optional":"true"},
        "locale":{"Key":"false", "Type":"string", "Optional":"true"},
        "version":{"Key":"false", "Type":"string", "Optional":"true"}
      }
    },
    "Method":{
      "Name":"GET"
    }
  },

  "Child Resources":[
    "http://localhost:4848/management/domain/configs",
    "http://localhost:4848/management/domain/resources",
    "http://localhost:4848/management/domain/servers",
    "http://localhost:4848/management/domain/property",
    "http://localhost:4848/management/domain/applications",
    "http://localhost:4848/management/domain/system-applications",
    "http://localhost:4848/management/domain/stop",
    "http://localhost:4848/management/domain/restart",
    "http://localhost:4848/management/domain/uptime",
    "http://localhost:4848/management/domain/version",
    "http://localhost:4848/management/domain/rotate-log",
    "http://localhost:4848/management/domain/host-port"
  ]

}

XML Resource Representation

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

<resource attributes>

    <Methods>
        method-list
    </Methods>
children
</type>

The replaceable items in this format are as follows:

resource: The name of the resource.
attributes: Zero or more name-value pairs separated by a space. Each name-value pair is specified as name="value".
method-list: One or more XML elements that represent the methods that the resource supports. For the format of each element, see XML Representation of a Resource Method.
children: 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 Resource Method

The XML representation of a method in a method list is as follows:

<Method name="method-name">
    <Message-Parameters>
        message-parameter-list
    </Message-Parameters>
    <Query-Parameters>
        query-parameter-list
    </Query-Parameters>
</Method>

The replaceable items in this format are as follows:

method-name: The name of the method, which is GET, POST, or DELETE.
message-parameter-list: Zero or more XML elements separated by a line feed that represent the message parameters that are allowed for the method. For the format of each element, see XML Representation of a Message Parameter or a Query Parameter.
query-parameter-list: Zero or more XML elements separated by a line feed that represent the query parameters that are allowed for the method. For the format of each element, see XML Representation of a Message Parameter or a Query Parameter.

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-name attribute-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.

Line breaks are added to enhance readability.

<Domain log-root="${com.sun.aas.instanceRoot}/logs" 
application-root="${com.sun.aas.instanceRoot}/applications" locale="" version="73">

  <Methods>
    <Method name="POST">
      <Message-Parameters>
        <log-root Key="false" Type="string" Optional="true"/>
        <application-root Key="false" Type="string" Optional="true"/>
        <locale Key="false" Type="string" Optional="true"/>
        <version Key="false" Type="string" Optional="true"/>
      </Message-Parameters>
    </Method>
    <Method name="GET">
    </Method>
  </Methods>

  <Child-Resources>
    <Child-Resource>http://localhost:4848/management/domain/configs</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/resources</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/servers</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/property</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/applications</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/system-applications</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/stop</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/restart</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/uptime</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/version</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/rotate-log</Child-Resource>
    <Child-Resource>http://localhost:4848/management/domain/host-port</Child-Resource>
  </Child-Resources>

</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 Sun GlassFish^TM Enterprise Server v3 environment by using the asadmin command-line utility.

The following topics are addressed here:

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

The following topics are addressed here:

To Create a Domain

After installing Enterprise 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

Create a domain by using the create-domain(1) subcommand.

Information about the options for this subcommand is included in this help page.

Type an admin user name and password for the domain.

To avoid setting up an admin login, you can accept the default admin, with no password. Pressing Return also selects the default.

Example 3–1 Creating a Domain

This example creates a domain named domain1 . When you type the command, you might be prompted for login information.

asadmin> create-domain --adminport 4848 domain1
Enter admin user name[Enter to accept default]>
Using port 4848 for Admin.
Default port 8080 for HTTP Instance is in use. Using 1161
Using default port 7676 for JMS.
Using default port 3700 for IIOP.
Using default port 8081 for HTTP_SSL.
Using default port 3820 for IIOP_SSL.
Using default port 3920 for IIOP_MUTUALAUTH.
Default port 8686 for JMX_ADMIN is in use. Using 1162
Distinguished Name of the self-signed X.509 Server Certificate is:
[CN=moonbeam.gateway.2wire.net,OU=GlassFish,O=Sun Microsystems,L=Santa Clara,ST
California,C=US]
Domain domain1 created.
Command create-domain executed successfully.

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

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.

List domains by using the list-domains(1) subcommand.

Example 3–2 Listing Domains

This example lists the domains in the default as-install/domains directory:

asadmin> list-domains
Name: domain1 Status: Running
Name: domain4 Status: Not Running
Name: domain6 Status: Not Running
Command list-domains executed successfully.

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:

1. The server (domain) uses file realm for authentication of admin users.

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

3. That one user has no 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 administration user is admin with no password. If #3 is not true, you will need to specify the password. If #2 is not true, you will also need to specify the user name. If #1 is not true, you will need to specify the user name and 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.

Determine the name of the domain that you are logging in to.

To list the existing domains:
asadmin list-domains

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.

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.

Before You Begin

A domain must be stopped before it can be deleted.

List domains by using the list-domains(1) subcommand.

If necessary, notify domain users that the domain is being deleted.

Ensure that the domain you want to delete is stopped.

If needed, see To Stop a Domain.

Delete the domain by using the delete-domain(1) subcommand.

Example 3–5 Deleting a Domain

This example deletes a domain named domain1 from the location specified.

asadmin> delete-domain --domaindir ..\domains domain1
Domain domain1 deleted.
Command delete-domain executed successfully.

Starting and Stopping a Domain

The following topics are addressed here:

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.

If you want the domain you are starting to be able to use the restart-domain subcommand, the --watchdog option must be set to true (true is the default). If you have set the --watchdog option to false, the domain will not be able to use the restart-domain subcommand.

Note –

For Microsoft Windows, you can use an alternate method to start a domain. From the Windows Start menu, select Programs -> Sun Microsystems ->Enterprise Server -> Start Admin Server.

This subcommand is supported in local mode only.

Start a domain by using the start-domain(1) subcommand.

Example 3–6 Starting a Domain

This example starts domain2 in the default domain directory.

asadmin> start-domain domain2

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

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 Programs -> Sun Microsystems -> Enterprise Server -> Stop Admin Server.

If necessary, notify users that you are going to stop the domain.

Stop the domain by using the stop-domain(1) subcommand.

Example 3–7 Stopping a Domain (or Server)

This example stops domain1 in the default directory, where domain1 is the only domain present in the directory.

asadmin> stop-domain
Waiting for the domain to stop ...........
Command stop-domain executed successfully.

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.

If the server will not restart, use the stop-domain(1) subcommand followed by the start-domain(1) subcommand.

Before You Begin

For the restart-domain subcommand to work, the --watchdog option of the start-domain subcommand must have been set to true (the default) when the domain was started. If this option was set to false and you attempt to restart the domain, the domain is stopped and a warning message is logged. If the --watchdog option is set to false, you can only restart the domain by using the stop-domain and start-domain subcommands.

Ensure that the server is running.

Remote subcommands require a running server.

Restart the domain by using the restart-domain(1) subcommand.

Example 3–8 Restarting a Domain (or Server)

This example restarts mydoimain4 in the default directory.

asadmin> restart-domain mydomain4
Waiting for the domain to restart ...........
Command restart-domain executed successfully.

Example 3–9 Restarting a Domain in a Browser

This example invokes the restart-domain subcommand in a browser.

http://yourhost:4848/__asadmin/restart-domain

Automatically Restarting a Domain

This section provides instructions for configuring your system to automatically restart the domain on Solaris.

The following topics are addressed here:

To Automatically Restart a Domain on Solaris 10

The create-service subcommand is supported on the Solaris and Windows platforms, however, only Solaris instructions are provided here.

On Solaris 10, you can use the asadmin create-service subcommand to create a Solaris Service Management Facility (SMF) service that restarts a Domain Administration Server (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 Solaris 10, the process requires the net_privaddr privilege. The privileged ports of the 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, the Solaris 10 administration commands such as svccfg, svcs, and auths must be available in the PATH.

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

Create the service by using the create-service(1) subcommand.

Information about properties for the subcommand is included in this help page.

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

For example:
svacdm enable /appserver/domains/domain1

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

This example creates a service .

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

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.

Add a line of text to the /etc/inittab file.

For example:
das:3:respawn:/opt/SUNWappserver/bin/asadmin start-domain --user admin --passwordfile /opt/SUNWappserver/password.txt domain1
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 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 Enterprise Server service to shut down. To prevent the service from shutting down when a user logs out, you must set the -Xrs Java 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 Enterprise Server service is running, restart the service for your changes to take affect.

Additional Domain Tasks

The following topics are addressed here:

To Display Domain Uptime

Use the uptime subcommand in remote mode to display the length of time that the domain administration server (DAS) has been running since it was last started.

Ensure that the server is running.

Remote subcommands require a running server.

Display uptime by using the uptime(1) subcommand.

Example 3–11 Displaying the DAS Uptime

This example displays the length of time that the DAS has been running.

asadmin> uptime
Uptime: 1 Weeks, 4 days, 0 hours, 17 minutes, 14 seconds, Total milliseconds: 951434595
Command uptime executed successfully.

To Switch a Domain to Another Supported Java Version

Enterprise Server v3 requires Version 6 Java SE platform as the underlying virtual machine for the Java^TM platform (Java Virtual Machine or JVM^TM machine).

Note –

Do not downgrade to an earlier Java version after a domain has been created with a newer JVM machine. If you must downgrade your JVM machine, downgrade it only for individual domains.

If you have not already done so, download the desired Java SDK (not the JRE) and install it on your system.

The Java SDK can be downloaded from http://java.sun.com/j2se.

Start the domain for which you are changing the JDK.

Use the following format:
as-install/bin/asadmin start-domain domain-name
For a valid JVM installation, locations are checked in the following order:
1. domain.xml (java-home inside java-config)
2. 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^TM platform (Java Virtual Machine) or JVM^TM machine) in the Sun GlassFish^TM Enterprise Server v3 environment by using the asadmin command-line utility.

The following topics are addressed here:

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

The following topics are addressed here:

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.

Ensure that the server is running.

Remote subcommands require a running server.

Create JVM options by using the create-jvm-options(1) subcommand.

To create more than one JVM option, use a colon (:) to separate the options. If the JVM option itself contains a colon (:), use the backslash (\) to offset the colon delimiter.

Information about properties for the subcommand is included in this help page.

To apply your changes, restart Enterprise Server. See To Restart a Domain.

Example 4–1 Creating JVM Options

This example sets multiple Java system properties.

asadmin> create-jvm-options -Dunixlocation=/root/example:
-Dvariable=\$HOME:
-Dwindowslocation=d\\:\\\sun\\\appserver:
-Doption1=-value1
created 4 option(s)
Command create-jvm-options executed successfully.

To List JVM Options

Use the list-jvm-options subcommand in remote mode to list the existing JVM options.

Ensure that the server is running.

Remote subcommands require a running server.

List JVM options by using the list-jvm-options(1) subcommand.

Example 4–2 Listing JVM Options

This example lists all JVM options.

asadmin> list-jvm-options
-Djava.security.auth.login.config=${com.sun.aas.instanceRoot}/config/login.conf
-XX: LogVMOutput
-XX: UnlockDiagnosticVMOptions
-Dcom.sun.enterprise.config.config_environment_factory_class=com.sun.enterprise.
config.serverbeans.AppserverConfigEnvironmentFactory
-Djavax.net.ssl.keyStore=${com.sun.aas.instanceRoot}/config/keystore.jks
-XX:NewRatio=2
-Djava.security.policy=${com.sun.aas.instanceRoot}/config/server.policy
-Djdbc.drivers=org.apache.derby.jdbc.ClientDriver
-Djavax.net.ssl.trustStore=${com.sun.aas.instanceRoot}/config/cacerts.jks
-client
-Djava.ext.dirs=${com.sun.aas.javaRoot}/lib/ext${path.separator}${com.sun.aas.ja
vaRoot}/jre/lib/ext${path.separator}${com.sun.aas.instanceRoot}/lib/ext${path.se
parator}${com.sun.aas.derbyRoot}/lib
-Xmx512m
-XX:LogFile=${com.sun.aas.instanceRoot}/logs/jvm.log
-Djava.endorsed.dirs=${com.sun.aas.installRoot}/lib/endorsed
Command list-jvm-options executed successfully.

To Delete JVM Options

Use the delete-jvm-options subcommand in remote mode to delete JVM options from the Java configuration or profiler elements of the domain.xml file.

Ensure that the server is running.

Remote subcommands require a running server.

List JVM options by using the list-jvm-options(1) subcommand.

If necessary, notify users that the JVM option is being deleted.

Delete JVM options by using the delete-jvm-options(1) subcommand.

To remove more than one JVM option, use a colon (:) to separate the options. If the JVM option itself contains a colon, use the backslash (\) to offset the colon delimiter.

To apply your changes, restart Enterprise Server. See To Restart a Domain.

Example 4–3 Deleting a JVM Option

This example removes a single JVM option.

asadmin> delete-jvm-options -Dopt1=A
deleted 1 option(s)
Command delete-jvm-options executed successfully.

Example 4–4 Deleting Multiple JVM Options

This example removes multiple JVM options.

asadmin> delete-jvm-options -Doption1=-value1:-Dvariable=\$HOME
deleted 2 option(s)
Command delete-jvm-options executed successfully.

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.

Ensure that the server is running.

Remote subcommands require a running server.

Generate the report by using the generate-jvm-report(1) subcommand.

Example 4–5 Generating a JVM Report

This example displays summary information about the threads, classes, and memory.

asadmin> generate-jvm-report --type summary 
Operating System Information:
Name of the Operating System: Windows XP
Binary Architecture name of the Operating System: x86, Version: 5.1
Number of processors available on the Operating System: 2
System load on the available processors for the last minute: NOT_AVAILABLE. 
(Sum of running and queued runnable entities per minute).
.
,
.
user.home = C:\Documents and Settings\Jennifer
user.language = en
user.name = Jennifer
user.timezone = America/New_York
user.variant =
variable = \$HOME
web.home = C:\Preview\v3_Preview_release\distributions\web\target\
glassfish\modules\web
Command generate-jvm-report executed successfully.

Administering the Profiler

A profiler generates information used to analyze server performance. The following topics are addressed here:

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.

Ensure that the server is running.

Remote subcommands require a running server.

Create a profiler by using the create-profiler(1) subcommand.

Information about properties for the subcommand is included in this help page.

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

Example 4–6 Creating a Profiler

This example creates a profiler named sample_profiler.

asadmin> create-profiler --classpath=/home/appserver/ --nativelibrarypath=/u/home/lib
--enabled=false --property=defaultuser=admin:password=adminadmin sample_profiler
Command create-profiler executed successfully.

To Delete a Profiler

Use the delete-profiler subcommand in remote mode to delete the profiler element from the Java configuration. You can then create a new profiler.

Ensure that the server is running.

Remote subcommands require a running server.

Delete the profiler by using the delete-profiler(1) subcommand.

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

Example 4–7 Deleting a Profiler

This example deletes the profiler named sample_profiler.

asadmin> delete-profiler sample_profiler
Command delete-profiler executed successfully.

Chapter 5 Administering Thread Pools

This chapter provides procedures for administering thread pools in the Sun GlassFish^TM Enterprise Server v3 environment by using the asadmin command-line utility.

The following topics are addressed here:

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^TM platform (Java Virtual Machine) or JVM^TM machine) can support many threads of execution simultaneously. To help performance, Enterprise 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 Enterprise 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.

The following topics are addressed here:

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 Enterprise Server threads, thread starvation might occur. You can avoid this by dividing the Enterprise Server threads into different thread pools.

Ensure that the server is running.

Remote subcommands require a running server.

Create a new thread pool by using the create-threadpool(1) subcommand.

Information about options for the subcommand is included in this help page.

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

Note –
Restart is not necessary for thread pools used by the web container.

Example 5–1 Creating a Thread Pool

This example creates threadpool-l.

asadmin> create-threadpool --maxthreadpoolsize 100 
      --minthreadpoolsize 20 --idletimeout 2 --workqueues 100 threadpool-1
Command create-threadpool executed successfully

To List Thread Pools

Use the list-threadpools subcommand in remote mode to list the existing thread pools.

Ensure that the server is running.

Remote subcommands require a running server.

List the existing thread pools by using the list-threadpools(1) subcommand.

Example 5–2 Listing Thread Pools

This example lists the existing thread pools.

asadmin> list-threadpools
threadpool-1
Command list-threadpools executed successfully

To Update a Thread Pool

Use the set subcommand to update the values for a specified thread pool.

List the existing thread pools by using the list-threadpools(1) subcommand.

Modify the values for a thread pool by using the set(1) subcommand.

The thread pool is identified by its dotted name.

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

Note –
Restart is not necessary for thread pools used by the web container.

Example 5–3 Updating a Thread Pool

This example sets the max-thread-pool-size from its previous value to 8.

asadmin> set server.thread-pools.thread-pool.http-thread-pool.max-thread-pool-size=8
Command set executed successfully

To Delete a Thread Pool

Use the delete-threadpool subcommand in remote mode to delete an existing thread pool. Deleting a thread pool will fail if that pool is referenced by a network listener.

Ensure that the server is running.

Remote subcommands require a running server.

List the existing thread pools by using the list-threadpools(1) subcommand.

Delete the specified thread pool by using the delete-threadpool(1) subcommand.

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

Note –
Restart is not necessary for thread pools used by the web container.

Example 5–4 Deleting a Thread Pool

This example deletes threadpool-1.

asadmin> delete-threadpool threadpool-1
Command delete-threadpool executed successfully

Chapter 6 Administering Web Applications

This chapter explains how to administer web applications in the Sun GlassFish^TM Enterprise Server v3 environment.

The following topics are addressed here:

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

http://localhost:8080/MortPages/calcMortgage?rate=8.0&per=360&bal=180000

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.

<init-param>
   <param-name>listings</param-name>
   <param-value>true</param-value>
</init-param>

If listings is set to true, you can also determine how directory listings are sorted. Set the value of the init-param named sortedBy to NAME, SIZE, or LAST_MODIFIED. Then restart the server.

<init-param>
   <param-name>sortedBy</param-name>
   <param-value>LAST_MODIFIED</param-value>
</init-param>

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.

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

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

This example redirects from dummy to etude:

<property name="redirect_1" value="from=/dummy url-prefix=http://etude"/>

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 Enterprise Server, you can front Enterprise 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.

The following topics are addressed here:

To Enable `mod_jk`

You can front Enterprise Server with Apache HTTP Server by enabling the mod_jk protocol for one of Enterprise 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^TM Pages (JSPs), forwarded to, and handled by the Enterprise 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 con nectors under different virtual servers by using the network listener attribute jk-enabled.

Install Apache HTTP Server and mod_jk.
- For information on installing Apache HTTP Server, see http://httpd.apache.org/docs/2.0/install.html.
- For information on installing mod_jk, see http://tomcat.apache.org/connectors-doc/webserver_howto/apache.html.

Configure the following files:
- apache2/conf/httpd.conf, the main Apache configuration file
- apache2/config/workers.properties or domain-dir/config/glassfish-jk.properties (to use non-default values of attributes described at http://tomcat.apache.org/tomcat-5.5-doc/config/ajp.html)
If you use both the workers.properties file and the glassfish-jk.properties file, the file referenced by httpd.conf first takes precedence.

Start Apache HTTP Server (httpd).

Start Enterprise Server with at least one web application deployed.

In order for the mod_jk–enabled network listener to start listening for requests, the web container must be started. Normally, this is achieved by deploying a web application.

Create an HTTP listener by using the create-http-listener(1)subcommand.

Use the following format:
asadmin> create-http-listener --listenerport 8009 --listeneraddress 0.0.0.0 --defaultvs server listener-name
where listener-name is the name of the new listener.

Enable mod_jk by using the set(1) subcommand.

Use the following format:
asadmin> set server-config.network-config.network-listeners. network-listener.listener-name.jk-enabled=true
where listener-name is the ID of the network listener for which mod_jk is being enabled.

If you are using the glassfish-jk.properties file and not referencing it in the httpd.conf file, point to the properties file by using the create-jvm-options(1) subcommand.

Use the following format:
asadmin> create-jvm-options -Dcom.sun.enterprise.web.connector.enableJK.propertyFile= domain-dir/config/glassfish-jk.properties

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

Example 6–4 `httpd.conf` File for `mod_jk`

This example shows an httpd.conf file that is set for mod_jk.

LoadModule jk_module /usr/lib/httpd/modules/mod_jk.so
JkWorkersFile /etc/httpd/conf/worker.properties
# Where to put jk logs
JkLogFile /var/log/httpd/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel debug
# Select the log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# JkOptions indicate to send SSL KEY SIZE,
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories
# JkRequestLogFormat set the request format
JkRequestLogFormat "%w %V %T"
# Send all jsp requests to GlassFish
JkMount /*.jsp worker1
# Send all glassfish-test requests to GlassFish
JkMount /glassfish-test/* worker1

Example 6–5 `workers.properties` File for `mod_jk`

This example shows a workers.properties or glassfish-jk.properties file that is set for mod_jk.

# Define 1 real worker using ajp13
worker.list=worker1
# Set properties for worker1 (ajp13)
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009

To Load Balance Using `mod_jk` and Enterprise 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 Enterprise Server instance that is front-ended by the Apache load balancer must be configured with a unique jvmRoute system property.

On each of the instances, perform the steps in To Enable mod_jk.

If your instances run on the same machine, you must choose different JK ports. The ports must match worker.worker*.port in your workers.properties file. See the properties file in Example 6–5.

On each of the instances, create the jvmRoute system property of Enterprise Server by using the create-jvm-options(1) subcommand.

Use the following format:
asadmin> create-jvm-options "-DjvmRoute=/instance-worker-name"/
where instance-worker-name is the name of the worker that you defined to represent the instance in the workers.properties file.

To apply your changes, restart Apache HTTP Server and Enterprise Server.

Example 6–6 `httpd.conf` File for Load Balancing

This example shows an httpd.conf file that is set for load balancing.

LoadModule jk_module /usr/lib/httpd/modules/mod_jk.so 
JkWorkersFile /etc/httpd/conf/worker.properties 
# Where to put jk logs 
JkLogFile /var/log/httpd/mod_jk.log 
# Set the jk log level [debug/error/info] 
JkLogLevel debug 
# Select the log format 
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] " 
# JkOptions indicate to send SSL KEY SIZE, 
JkOptions +ForwardKeySize +ForwardURICompat -ForwardDirectories 
# JkRequestLogFormat set the request format 
JkRequestLogFormat "%w %V %T" 
# Send all jsp requests to GlassFish 
JkMount /*.jsp worker1 
# Send all glassfish-test requests to GlassFish 
JkMount /glassfish-test/* loadbalancer

Example 6–7 `workers.properties` File for Load Balancing

This example shows a workers.properties or glassfish-jk.properties file that is set for load balancing. The worker.worker*.port should match with JK ports you created.

worker.list=worker1,worker2,loadbalancer
worker.worker1.type=ajp13
worker.worker1.host=localhost
worker.worker1.port=8009
worker.worker1.lbfactor=1
worker.worker1.socket_keepalive=1
worker.worker1.socket_timeout=300
worker.worker2.type=ajp13
worker.worker2.host=localhost
worker.worker2.port=8010
worker.worker2.lbfactor=1
worker.worker2.socket_keepalive=1
worker.worker2.socket_timeout=300
worker.loadbalancer.type=lb
worker.loadbalancer.balance_workers=worker1,worker2

To Enable SSL Between the `mod_jk` Load Balancer and the Browser

To activate security for mod_jk on Enterprise 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.

Before You Begin

The mod_jk connector must be enabled.

Generate the private key as follows:
openssl genrsa -des3 -rand file1:file2:file3:file4:file5 -out server.key 1024
where file1:file2: and so on represents the random compressed files.

Remove the pass-phrase from the key as follows:
openssl rsa -in server.key -out server.pem

Generate the CSR is as follows:
openssl req -new -key server.pem -out server.csr
Enter the information you are prompted for.

Generate a temporary certificate as follows:
openssl x509 -req -days 60 -in server.csr -signkey server.pem -out server.crt
This temporary certificate is good for 60 days.

Create the ssl.conf file under the /etc/apache2/conf.d directory.

In the ssl.conf file, add one of the following redirects:
- Redirect a web application, for example, JkMount /hello/* worker1.
- Redirect all requests, for example, JkMount /* worker1.
# Send all jsp requests to GlassFish JkMount /*.jsp worker1 # Send all glassfish-test requests to GlassFish JkMount /glassfish-test/* loadbalancer

Example 6–8 `ssl.conf` File for `mod_jk` Security

A basic SSL-enabled virtual host will appear in the ssl.conf file. In this example, all requests are redirected.

Listen 443
<VirtualHost _default_:443>
SSLEngine on
SSLCipherSuite ALL:!ADH:!EXP56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL
SSLCertificateFile "/etc/apache2/2.2/server.crt"
SSLCertificateKeyFile "/etc/apache2/2.2/server.pem"
JkMount /* worker1
</VirtualHost>

To Enable SSL Between the `mod_jk` Load Balancer and Enterprise Server

Before You Begin

The self-signed certificate must be configured.

Perform the steps in To Enable mod_jk.

Start another Enterprise Server with at least one web application deployed.

In order for the mod_jk–enabled network listener to start listening for requests, the web container must be started. Normally, this is achieved by deploying a web application.

Follow instructions from To Configure an HTTP Listener for SSL on the mod_jk connector.

Use the following format:
asadmin> create-ssl --type http-listener --certname sampleCert new-listener

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

(Optional) To support both SSL and non-SSL connection, create two mod_jk–enabled network listeners and workers.

Example workers.properties file:

#This example shows a worker.properties
worker.list=ajp13unsecure, ajp13secure

worker.ajp13secure.type=ajp13 
worker.ajp13secure.host=localhost 
worker.ajp13secure.port=8009  

worker.ajp13unsecure.type=ajp13 
worker.ajp13unsecure.host=localhost 
worker.ajp13unsecure.port=8010

Secure and unsecure HTTP listeners with ports 8009 and 8010 are created and enabled for mod_jk. For instructions, see To Enable mod_jk.

To apply your changes, restart Apache HTTP Server and Enterprise Server.

Chapter 7 Administering the Logging Service

This chapter provides instructions on how to configure logging and how to view log information in the Sun GlassFish^TM Enterprise Server v3 environment.

The following topics are addressed here:

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

The following topics are addressed here:

Log File

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

Enterprise Server log records follow a uniform format:

[#|yyyy-mm-ddThh:mm:ss.SSS-Z|Log Level|ProductName-Version|LoggerName|Key Value Pairs|Message|#]

[# and #] mark the beginning and end of the record.
The vertical bar (|) separates the fields of the record.
yyyy-mm-ddThh:mm:ss.SSSS-Z specifies the date and time that the record was created. For example: 2006-10-21T13:25:53.852-0400
Log Level specifies the desired log level. You can select any of the following values: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST. The default is INFO.
ProductName-Version refers to the current version of the Enterprise Server. For example: glassfish
LoggerName is a hierarchical logger namespace that identifies the source of the log module. For example: javax.enterprise.system.core
Key Value Pairs refers to pairs of key names and values, typically a thread ID. For example: _ThreadID=14;
Message is the text of the log message. For all Enterprise 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

An example log record might look like this:

[#|2006-10-21T13:25:53.852-0400|INFO|GlassFish10.0|javax.enterprise.
system.core|_ThreadID=13;|CORE5004: Resource Deployed: 
[cr:jms/DurableConnectionFactory].|#]

The Administration Console presents log records in a more readable display.

Logger Namespaces

You can use the list-logger-levels(1) subcommand to list the existing loggers for the modules. Example loggers:

javax.enterprise.system.container.cmp: INFO
javax.enterprise.system.tools.admin: INFO
javax.enterprise.system.container.web: INFO
javax.enterprise.system.util: INFO
javax.enterprise.resource.webcontainer.jsf.timing: INFO
javax: INFO
javax.enterprise.resource.corba: INFO
javax.enterprise.system.core.naming: INFO
javax.enterprise.system.core.selfmanagement: INFO
javax.enterprise.system.container.ejb: INFO
javax.enterprise.resource.webcontainer.jsf.config: INFO
javax.enterprise.resource.javamail: INFO
org.apache.catalina: INFO
javax.enterprise.system.core.config: INFO
javax.enterprise.system.webservices.rpc: INFO
javax.enterprise.system.webservices.registry: INFO
javax.enterprise.system.tools.deployment: INFO
javax.enterprise.resource.jms: INFO
javax.enterprise.system: INFO
javax.enterprise.system.webservices.saaj: INFO
org.apache.jasper: INFO
javax.enterprise.resource.webcontainer.jsf.lifecycle: INFO
javax.enterprise.resource.jta: INFO
javax.enterprise.resource.jdo: INFO
javax.enterprise.resource.resourceadapter: INFO
javax.enterprise.system.core.transaction: INFO
javax.enterprise.resource.webcontainer.jsf.resource: INFO
javax.enterprise.system.core.security: INFO
javax.enterprise.resource.webcontainer.jsf.application: INFO
javax.enterprise.system.core.classloading: INFO
org.apache.coyote: INFO
javax.enterprise.resource.webcontainer.jsf.managedbean: INFO
javax.enterprise.system.container.ejb.mdb: INFO
javax.enterprise.resource.webcontainer.jsf.context: INFO
javax.enterprise.resource.webcontainer.jsf.renderkit: INFO
javax.enterprise.resource.webcontainer.jsf.facelets: INFO
javax.enterprise.resource.webcontainer.jsf.taglib: INFO

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 Enterprise Server for changes to take effect.

The following topics are addressed here:

To List the Logger Levels

Use the list-logger-levels subcommand in remote mode to list the modules and their current log levels.

Ensure that the server is running.

Remote subcommands require a running server.

List the existing module loggers by using the list-logger-levels(1) subcommand.

Example 7–1 Listing Logger Levels for Modules

This example shows a partial list of the existing loggers and indicates how their log levels are set.

asadmin> list-logger-levels
javax.enterprise.system.container.cmp: INFO
javax.enterprise.system.tools.admin: INFO
java.util.logging.ConsoleHandler: FINEST
javax.enterprise.system.container.web: INFO
javax.enterprise.system.util: INFO
javax.enterprise.resource.webcontainer.jsf.timing: INFO
javax: INFO
javax.enterprise.resource.corba: INFO
...
Command list-logger-levels executed successfully.

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:

java.util.logging.ConsoleHandler.level = INFO 
java.util.logging.ConsoleHandler.formatter = 
com.sun.enterprise.server.logging.UniformLogFormatter

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

#javax.enterprise.system.tools.level=FINE
#javax.enterprise.system.container.ejb.level=FINE
#javax.enterprise.system.core.security.level=FINE
#javax.enterprise.system.tools.admin.level=FINE
#javax.enterprise.level=FINE
#javax.enterprise.system.container.web.level=FINE

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

Ensure that the server is running.

Remote subcommands require a running server.

List the existing module loggers by using the list-logger-levels(1) subcommand.

Set the log level for a module by using the set-log-level(1) subcommand.

Your choices are SEVERE, WARNING, INFO, CONFIG, FINE, FINER, and FINEST.

Example 7–3 Setting the Log Level for a Module Logger

This example sets the log level for the web container logger to FINE.

asadmin> set-log-level javax.enterprise.system.container.web.level=FINE
Command set-log-level executed successfully.

Example 7–4 Setting Log Levels for Multiple Loggers

This example sets the log level for security and web container loggers.

asadmin> set-log-level javax.enterprise.system.core.security.level=FINE
javax.enterprise.system.container.web=WARNING 
Command set-log-level executed successfully.

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 Enterprise Server for changes to take effect.

Ensure that the server is running.

Remote subcommands require a running server.

Rotate a log by using the rotate-log(1) subcommand.

Example 7–5 Rotating a Log File Manually

This example moves the server.log file to yyyy-mm-dd_server.log and creates a new server.log file in the default location.

asadmin> rotate-log
Command rotate-log executed successfuly.

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 Sun GlassFish^TM Enterprise Server v3 components and services by using the asadmin command-line utility. Instructions for configuring JConsole to monitor Enterprise Server resources are also provided.

The following topics are addressed here:

Instructions for monitoring by using the Administration Console are contained in the Administration Console online help.

For information on using REST interfaces for monitoring, see Using REST Interfaces to Administer Enterprise Server.

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

The following topics are addressed here:

How the Monitoring Tree Structure Works

A monitorable object is a component, subcomponent, or service that can be monitored. Enterprise Server uses a tree structure to track monitorable objects. Because the tree is dynamic, the tree changes as Enterprise 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:

asadmin> list --monitor "server.*"

server.applications
server.connector-service
server.http-service
server.jms-service
server.containers.jruby
server.jvm
server.network
server.orb
server.resources 
server.security
server.thread-pool
server.transaction-service
server.web

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.

The following node tree hierarchies are addressed here:

Applications Tree Hierarchy

The applications tree contains the following nodes:

server.applications
   |--- application1
   |    |--- ejb-module-1
   |    |        |--- ejb1 *
   |    |                  |--- bean-cache (for entity/sfsb) *
   |    |                  |--- bean-pool (for slsb/mdb/entity) *
   |    |                  |--- bean-methods
   |    |                       |---method1 *
   |    |                       |---method2 *
   |    |                  |--- timers (for s1sb/entity/mdb) *
   |    |--- web-module-1
   |    |        |--- virtual-server-1 *
   |    |                       |---servlet1  *
   |    |                       |---servlet2  *
   |--- standalone-web-module-1
   |    |        |----- virtual-server-2 *
   |    |                       |---servlet3 *
   |    |                       |---servlet4 *
   |    |        |----- virtual-server-3 *
   |    |                       |---servlet3 *(same servlet on different vs)
   |    |                       |---servlet5 *
   |--- standalone-ejb-module-1
   |    |        |--- ejb2 *
   |    |                  |--- bean-cache (for entity/sfsb) *
   |    |                  |--- bean-pool (for slsb/mdb/entity) *
   |    |                  |--- bean-methods
   |    |                       |--- method1 *
   |    |                       |--- method2 *
   |    |                  |--- timers (for s1sb/entity/mdb) *
   |--- jersey-application-1
   |    |--- jersey
   |    |        |--- resources
                           resource-0
                               hitcount
                                    *statistic   
   |--- application2

An example dotted name might be server.applications.hello.server.request.maxtime.

An example dotted name under the EJB method node might be server.applications.ejbsfapp1.ejbsfapp1ejbmod1\.jar.SFApp1EJB1.

An example Jersey dotted name might be server.applications.helloworld-webapp.jersey.resources.resource-0.hitcount.resourcehitcount-count.

For available statistics, see EJB Statistics, Jersey Statistics, and Web Statistics.

Connector Service Tree Hierarchy

The connector-service tree holds monitorable attributes for pools such as the connector connection pool. The connector-service tree contains the following nodes:

server.connector-service
        resource-adapter-1
             connection-pools
                  pool-1
             work-management

An example dotted name might be server.connector-service.resource-adapter-1.connection-pools.pool-1. For available statistics, see JMS/Connector Service Statistics.

HTTP Service Tree Hierarchy

The http-service tree contains the following nodes:

server.http-service
       virtual-server
           request
               *statistic
       _asadmin
           request
               *statistic

An example dotted name under the virutal-server node might be server.http-service.virtual-server1.request.requestcount. For available statistics, see HTTP Service Statistics.

JMS/Container Service Tree Hierarchy

The jms-service tree holds monitorable attributes for connection factories (connection pools for resource adapters) and work management (for Message Queue resource adapters). The jms-service tree contains the following nodes:

server.jms-service
        connection-factories
             connection-factory-1
        work-management

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.

JRuby Tree Hierarchy

The jruby tree contains the following nodes:

server.containers.jruby.applications
         jruby-application
               *statistic
               http
                   *statistic
               runtime-pool
                   *statistic

For available statistics, see JRuby Statistics.

JVM Tree Hierarchy

The jvm tree contains the following nodes:

server.jvm
           class-loading-system
           compilation-system
           garbage-collectors
           memory
           operating-system
           runtime

An example dotted name under the memory node might be server.jvm.memory.maxheapsize. For available statistics, see JVM Statistics.

Network Tree Hierarchy

The network statistics apply to the network listener, such as admin-listener, http-listener-1, ttp-listener-2. The network tree contains the following nodes:

server.network
          type-of-listener
              keep-alive
                    *statistic
              file-cache
                    *statistic
              thread-pool
                    *statistic
              connection-queue
                     *statistic

An example dotted name under the network node might be server.network.admin-listener.keep-alive.maxrequests-count. For available statistics, see Network Statistics.

ORB Tree Hierarchy

The orb tree holds monitorable attributes for connection managers. The orb tree contains the following nodes:

server.orb
    transport
        connectioncache
            inbound
                *statistic
            outbound
                *statistic

An example dotted name might be server.orb.transport.connectioncache.inbound.connectionsidle-count. For available statistics, see ORB Statistics (Connection Manager).

Resources Tree Hierarchy

The resources tree holds monitorable attributes for pools such as the JDBC connection pool and connector connection pool. The resources tree contains the following nodes:

server.resources
       connection-pool
           request
               *statistic

An example dotted name might be server.resources.jdbc-connection-pool1.numconnfree.count. For available statistics, see Resource Statistics (Connection Pool).

Security Tree Hierarchy

The security tree contains the following nodes:

server.security
       ejb
          *statistic
       web
          *statistic
       realm
          *statistic

An example dotted name might be server.security.realm.realmcount-starttime. For available statistics, see Security Statistics.

Thread Pool Tree Hierarchy

The thread-pool tree holds monitorable attributes for connection managers, and contains the following nodes:

server.thread-pool
                orb
                    threadpool
                            thread-pool-1
                                *statistic

An example dotted name might be server.thread-pool.orb.threadpool.thread-pool-1.averagetimeinqueue-current. For available statistics, see Thread Pool Statistics.

Transactions Service Tree Hierarchy

The transaction-service tree holds monitorable attributes for the transaction subsystem for the purpose of rolling back transactions. The transaction-service tree contains the following nodes:

server.transaction-service
         statistic

An example dotted name might be server.tranaction-service.activeids. For available statistics, see Transaction Service Statistics.

Web Tree Hierarchy

The web tree contains the following nodes:

server.web
           jsp
              *statistic
           servlet
              *statistic
           session
              *statistic
           request
              *statistic

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 Enterprise Server can gather at runtime. Adding monitoring capabilities enables an add-on component to provide statistics to Enterprise Server in the same way as components that are supplied in the Enterprise Server distributions. As a result, you can use the same administrative interfaces to monitor statistics from any installed Enterprise Server component, regardless of the origin of the component.

Tools for Monitoring Enterprise Server

The following asadmin subcommands are provided for monitoring the services and components of Enterprise 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 list --monitor subcommand is used to display the objects that can be monitored with the monitor subcommand. For guidelines and instructions, see Guidelines for Using the list and get Subcommands for Monitoring.
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 Enterprise 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
OFF. No monitoring, no impact on performance

The following tasks are addressed here:

To Enable Monitoring

Use the enable-monitoring subcommand to enable the monitoring service itself, or to enable monitoring for individual modules. Monitoring is immediately activated, without restarting Enterprise Server.

You can also use the set(1) subcommand to enable monitoring for a module. Using the set command is not a dynamic procedure, so you need to restart Enterprise Server for your changes to take effect.

Determine which services and components are currently enabled for monitoring.

asadmin> get server.monitoring-service.module-monitoring-levels.*

This example output shows that the HTTP service is not enabled (OFF for monitoring), but other objects are enabled:

configs.config.server-config.monitoring-service.module-monitoring-levels.web-container=HIGH
       configs.config.server-config.monitoring-service.module-monitoring-levels.http-service=OFF
           configs.config.server-config.monitoring-service.module-monitoring-levels.jvm=HIGH

Enable monitoring by using the enable-monitoring(1) subcommand.

Server restart is not required.

Example 8–1 Enabling the Monitoring Service Dynamically

This example enables the monitoring service without affecting monitoring for individual modules.

asadmin> enable-monitoring
Command enable-monitoring executed successfully

Example 8–2 Enabling Monitoring for Modules Dynamically

This example enables monitoring for the ejb-container module.

asadmin> enable-monitoring --level ejb-container=HIGH
Command enable-monitoring executed successfully

Example 8–3 Enabling Monitoring for Modules by Using the `set` Subcommand

This example enables monitoring for the HTTP service by setting the monitoring level to HIGH (you must restart the server for changes to take effect).

asadmin> set server.monitoring-service.module-monitoring-levels.http-service=HIGH
Command set executed successfully

To Disable Monitoring

Use the disable-monitoring subcommand to disable the monitoring service itself, or to disable monitoring for individual modules. Monitoring is immediately stopped, without restarting Enterprise Server.

You can also use the set(1) subcommand to disable monitoring for a module. Using the set command is not a dynamic procedure, so you need to restart Enterprise Server for your changes to take effect.

Determine which services and components currently are enabled for monitoring.

asadmin get server.monitoring-service.module-monitoring-levels.*

This example output shows that monitoring is enabled for web-container, http-service, and jvm:

configs.config.server-config.monitoring-service.module-monitoring-levels.web-container=HIGH
       configs.config.server-config.monitoring-service.module-monitoring-levels.http-service=HIGH
              configs.config.server-config.monitoring-service.module-monitoring-levels.jvm=HIGH

Disable monitoring for a service or module by using the disable-monitoring(1) subcommand.

Server restart is not required

Example 8–4 Disabling the Monitoring Service Dynamically

This example disables the monitoring service without changing the monitoring levels for individual modules.

asadmin> disable-monitoring
Command disable-monitoring executed successfully

Example 8–5 Disabling Monitoring for Modules Dynamically

This example disables monitoring for specific modules. Their monitoring levels are set to OFF.

asadmin> disable-monitoring --modules web-container,ejb-container
Command disable-monitoring executed successfully

Example 8–6 Disabling Monitoring by Using the `set` Subcommand

This example disables monitoring for the HTTP service (you must restart the server for changes to take affect).

asadmin> set server.monitoring-service.module-monitoring-levels.http-service=OFF
Command set executed successfully

Viewing Common Monitoring Data

Use the monitor subcommand to display basic data on commonly-monitored objects.

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 .

Determine which type of monitorable object you want to monitor.

Your choices for v3 are jvm, httplistener, and webmodule.

Request the monitoring data by using the monitor(1) subcommand.

Example 8–7 Viewing Common Monitoring Data

This example requests common data for type jvm on instance server.

asadmin> monitor --type jvm server

UpTime(ms)                          Heap and NonHeap Memory(bytes)
current                   min        max        low        high       count

9437266                   8585216    619642880  0          0          93093888
9467250                   8585216    619642880  0          0          93093888

Common Monitoring Statistics

Common monitoring statistics are described in the following sections:

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^TM (JSP^TM) 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.

The following topics are addressed here:

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.

For detailed information on dotted names, see the dotted-names(5ASC) help page.

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.
asadmin> list --monitor "*" server.web server.connector-service server.orb server.jms-serviceserver.jvm server.applications server.http-service server.thread-pools

Get data for a monitored component or service by using the get(1) subcommand.

Example 8–8 Viewing Attributes for a Specific Type

This example gets information about all the attributes for object type jvm on instance server.

asadmin> get --monitor server.jvm.*
server.jvm.class-loading-system.loadedclasscount = 3715
server.jvm.class-loading-system.totalloadedclasscount = 3731
server.jvm.class-loading-system.unloadedclasscount = 16
server.jvm.compilation-system.name-current = HotSpot Client Compiler
server.jvm.compilation-system.totalcompilationtime = 769
server.jvm.garbage-collectors.Copy.collectioncount = 285
server.jvm.garbage-collectors.Copy.collectiontime = 980
server.jvm.garbage-collectors.MarkSweepCompact.collectioncount = 2
server.jvm.garbage-collectors.MarkSweepCompact.collectiontime = 383
server.jvm.memory.committedheapsize = 23498752
server.jvm.memory.committednonheapsize = 13598720
server.jvm.memory.initheapsize = 0
server.jvm.memory.initnonheapsize = 8585216
server.jvm.memory.maxheapsize = 66650112
server.jvm.memory.maxnonheapsize = 100663296
server.jvm.memory.objectpendingfinalizationcount = 0
server.jvm.memory.usedheapsize = 19741184
server.jvm.memory.usednonheapsize = 13398352
server.jvm.operating-system.arch-current = x86
server.jvm.operating-system.availableprocessors = 2
server.jvm.operating-system.name-current = Windows XP
server.jvm.operating-system.version-current = 5.1
server.jvm.runtime.classpath-current = glassfish.jar
server.jvm.runtime.inputarguments-current = []
server.jvm.runtime.managementspecversion-current = 1.0
server.jvm.runtime.name-current = 4372@ABBAGANI_WORK
server.jvm.runtime.specname-current = Java Virtual Machine Specification
server.jvm.runtime.specvendor-current = Sun Microsystems Inc.
server.jvm.runtime.specversion-current = 1.0
server.jvm.runtime.uptime = 84813
server.jvm.runtime.vmname-current = Java HotSpot(TM) Client VM
server.jvm.runtime.vmvendor-current = Sun Microsystems Inc.
server.jvm.runtime.vmversion-current = 1.5.0_11-b03

Example 8–9 Viewing Monitorable Applications

This example lists all the monitorable applications for instance server.

asadmin> list --monitor server.applications.*
server.applications.app1
server.applications.app2
server.applications.app1.virtual-server1
server.applications.app2.virtual-server1

Example 8–10 Viewing Attributes for an Application

This example gets information about all the attributes for application hello.

asadmin> get --monitor server.applications.hello.*
server.applications.hello.server.activatedsessionstotal = 0
server.applications.hello.server.activejspsloadedcount = 1
server.applications.hello.server.activeservletsloadedcount = 1
server.applications.hello.server.activesessionscurrent = 1
server.applications.hello.server.activesessionshigh = 1
server.applications.hello.server.errorcount = 0
server.applications.hello.server.expiredsessionstotal = 0
server.applications.hello.server.maxjspsloadedcount = 1
server.applications.hello.server.maxservletsloadedcount = 0
server.applications.hello.server.maxtime = 0
server.applications.hello.server.passivatedsessionstotal = 0
server.applications.hello.server.persistedsessionstotal = 0
server.applications.hello.server.processingtime = 0.0
server.applications.hello.server.rejectedsessionstotal = 0
server.applications.hello.server.requestcount = 0
server.applications.hello.server.sessionstotal = 
server.applications.hello.server.totaljspsloadedcount = 0
server.applications.hello.server.totalservletsloadedcount = 0

Example 8–11 Viewing a Specific Attribute

This example gets information about the jvm attribute runtime.vmversion-current on instance server.

asadmin> get --monitor server.jvm.runtime.vmversion-current
server.jvm.runtime.vmversion-current = 10.0-b23

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 Statistics

EJBs fit into the tree of objects as shown in Applications Tree Hierarchy. Use the following dotted name pattern to get applications statistics:

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

Statistics available for applications are shown in the following sections:

EJB Cache Statistics

Use the following dotted name pattern for EJB cache statistics:

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

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

Table 8–5 EJB Cache Monitoring Statistics


Statistic	Data Type	Description
`cachemisses`	RangeStatistic	The number of times a user request does not find a bean in the cache.
`cachehits`	RangeStatistic	The number of times a user request found an entry in the cache.
`numbeansincache`	RangeStatistic	The number of beans in the cache. This is the current size of the cache.
`numpassivations`	CountStatistic	Number of passivated beans. Applies only to stateful session beans.
`numpassivationerrors`	CountStatistic	Number of errors during passivation. Applies only to stateful session beans.
`numexpiredsessionsremoved`	CountStatistic	Number of expired sessions removed by the cleanup thread. Applies only to stateful session beans.
`numpassivationsuccess`	CountStatistic	Number of times passivation completed successfully. Applies only to stateful session beans.

EJB Container Statistics

Use the following dotted name pattern for EJB container statistics:

server.applications.appname.ejbmodulename.container.ejbname

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

Table 8–6 EJB Container Monitoring Statistics


Statistic	Data Type	Description
`createcount`	CountStatistic	Number of times an EJB’s `create` method is called.
`messagecount`	CountStatistic	Number of messages received for a message-driven bean.
`methodreadycount`	RangeStatistic	Number of stateful or stateless session beans that are in the `MethodReady` state.
`passivecount`	RangeStatistic	Number of stateful session beans that are in `Passive` state.
`pooledcount`	RangeStatistic	Number of entity beans in pooled state.
`readycount`	RangeStatistic	Number of entity beans in ready state.
`removecount`	CountStatistic	Number of times an EJB’s `remove` method is called.

EJB Method Statistics

Use the following dotted name pattern for EJB method statistics:

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

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.

Table 8–9 Timer Monitoring Statistics


Statistic	Data Type	Description
`numtimerscreated`	CountStatistic	Number of timers created in the system.
`numtimersdelivered`	CountStatistic	Number of timers delivered by the system.
`numtimersremoved`	CountStatistic	Number of timers removed from the system.

HTTP Service Statistics

The HTTP service fits into the tree of objects as shown in HTTP Service Tree Hierarchy.

The HTTP service statistics are described in the following sections:

HTTP Service Virtual Server Statistics

HTTP Service Virtual Server Statistics

Use the following dotted name pattern for HTTP service virtual server statistics:

server.http-service.virtual-server.request.statistic

The HTTP service statistics for virtual servers are shown in the following table.

Table 8–10 HTTP Service Virtual Server Monitoring Statistics


Statistic	Data Type	Description
`count200`	CountStatistic	Number of responses with a status code equal to 200
`count2xx`	CountStatistic	Number of responses with a status code in the 2xx range
`count302`	CountStatistic	Number of responses with a status code equal to 302
`count304`	CountStatistic	Number of responses with a status code equal to 304
`count3xx`	CountStatistic	Number of responses with a status code equal in the 3xx range
`count400`	CountStatistic	Number of responses with a status code equal to 400
`count401`	CountStatistic	Number of responses with a status code equal to 401
`count403`	CountStatistic	Number of responses with a status code equal to 403
`count404`	CountStatistic	Number of responses with a status code equal to 404
`count4xx`	CountStatistic	Number of responses with a status code equal in the 4xx range
`count503`	CountStatistic	Number of responses with a status code equal to 503
`count5xx`	CountStatistic	Number of responses with a status code equal in the 5xx range
`countother`	CountStatistic	Number of responses with a status code outside the 2xx, 3xx, 4xx, and 5xx range
`errorcount`	CountStatistic	Cumulative value of the error count, with error count representing the number of cases where the response code was greater than or equal to 400
`hosts`	StringStatistic	The host (alias) names of the virtual server
`maxtime`	CountStatistic	Longest response time for a request; not a cumulative value, but the largest response time from among the response times
`processingtime`	CountStatistic	Cumulative value of the times taken to process each request, with processing time being the average of request processing times over the request count
`requestcount`	CountStatistic	Cumulative number of requests processed so far
`state`	StringStatistic	The state of the virtual server

Jersey Statistics

Jersey fits into the tree of objects as shown in Applications Tree Hierarchy.

Use the following dotted name pattern for Jersey statistics:

server.applications.jersey-application.jersey.resources.resource-0.hitcount.statistic

The statistics available for Jersey are shown in the following table.

Table 8–11 Jersey Statistics


Statistic	Data Type	Description
`resourcehitcount`	CountStatistic	Number of hits on this resource class
`rootresourcehitcount`	CountStatistic	Number of hits on this root resource class

JMS/Connector Service Statistics

The JMS/Connector Service fits into the tree of objects as shown in JMS/Container Service Tree Hierarchy.

JMS/Connector Service statistics are shown in the following sections:

Connector Connection Pool Statistics (JMS)

Use the following dotted name pattern for JMS/Connector Service connection pool statistics:

server.connector-service.resource-adapter-1.connection-pool.statistic

JMS/Connector Service statistics available for the connector connection pools are shown in the following table.

Table 8–12 Connector Connection Pool Monitoring Statistics (JMS)


Statistic	Data Type	Description
`averageconnwaittime`	CountStatistic	Average wait time of connections before they are serviced by the connection pool.
`connectionrequestwaittime`	RangeStatistic	The longest and shortest wait times of connection requests. The current value indicates the wait time of the last request that was serviced by the pool.
`numconnfailedvalidation`	CountStatistic	Total number of connections in the connection pool that failed validation from the start time until the last sample time.
`numconnused`	RangeStatistic	Total number of connections that are currently being used, as well as information about the maximum number of connections that were used (the high water mark).
`numconnfree`	RangeStatistic	Total number of free connections in the pool as of the last sampling.
`numconntimedout`	CountStatistic	Total number of connections in the pool that timed out between the start time and the last sample time.
`numconncreated`	CountStatistic	Number of physical connections, in milliseconds, that were created since the last reset.
`numconndestroyed`	CountStatistic	Number of physical connections that were destroyed since the last reset.
`numconnacquired`	CountStatistic	Number of logical connections acquired from the pool.
`numconnreleased`	CountStatistic	Number of logical connections released to the pool.
`waitqueuelenght`	CountStatistic	Number of connection requests in the queue waiting to be serviced.

Connector Work Management Statistics (JMS)

Use the following dotted name pattern for JMS/Connector Service work management statistics:

server.connector-service.resource-adapter-1.work-management.statistic

JMS/Connector Service statistics available for connector work management are listed in the following table.

Table 8–13 Connector Work Management Monitoring Statistics (JMS)


Statistic	Data Type	Description
`activeworkcount`	RangeStatistic	Number of work objects executed by the connector.
`completedworkcount`	CountStatistic	Number of work objects that were completed.
`rejectedworkcount`	CountStatistic	Number of work objects rejected by the Enterprise Server.
`submittedworkcount`	CountStatistic	Number of work objects submitted by a connector module.
`waitqueuelength`	RangeStatistic	Number of work objects waiting in the queue before executing.
`workrequestwaittime`	RangeStatistic	Longest and shortest wait of a work object before it gets executed.

JRuby Statistics

JRuby fits into the tree of objects as show in JRuby Tree Hierarchy.

The statistics that are available for JRuby are shown in the following sections:

JRuby Container Statistics

Use the following dotted name pattern for JRuby container statistics:

server.containers.jruby.applications.jruby-application.statistic

The statistics that are available for the JRuby container are shown in the following table.

Table 8–14 JRuby Container Statistics


Statistic	Data Type	Description
`environment`	StringStatistic	JRuby application environment
`appname`	StringStatistic	Ruby application name
`contextpath`	StringStatistic	Context path of Ruby application
`jrubyversion`	StringStatistic	JRuby version
`rubyframework`	StringStatistic	Ruby application framework

JRuby Runtime Statistics

Use the following dotted name pattern for JRuby runtime statistics:

server.containers.jruby.applications.jruby-application.runtime.statistic

The statistics that are available for the JRuby runtime are shown in the following table.

Table 8–15 JRuby Runtime Statistics


Statistic	Data Type	Description
`activeruntimes`	CountStatistic	Currently active runtimes
`appname`	StringStatistic	Ruby application name
`hardmaximum`	CountStatistic	Maximum active runtimes
`hardminimum`	CountStatistic	Minimum active runtimes

JRuby HTTP Service Statistics

Use the following dotted name pattern for JRuby HTTP service statistics:

server.containers.jruby.applications.jruby-application.http.statistic

The statistics that are available for the JRuby HTTP service are shown in the following table.

Table 8–16 JRuby HTTP Service Statistics


Statistic	Data Type	Description
`address`	StringStatistic	Server address
`appname`	StringStatistic	Ruby application name
`averageprocessingtime`	CountStatistic	Average request processing time in milliseconds
`contextpath`	StringStatistic	Context path of Ruby application
`count2xx`	CountStatistic	Number of responses with a status code in the 2xx range
`count200`	CountStatistic	Number of responses with a status code equal to 200
`count3xx`	CountStatistic	Number of responses with a status code in the 3xx range
`count302`	CountStatistic	Number of responses with a status code equal to 302
`Count304`	CountStatistic	Number of responses with a status code equal to 304
`count4xx`	CountStatistic	Number of responses with a status code in the 4xx range
`count400`	CountStatistic	Number of responses with a status code equal to 400
`count401`	CountStatistic	Number of responses with a status code equal to 401
`count403`	CountStatistic	Number of responses with a status code equal to 403
`count404`	CountStatistic	Number of responses with a status code equal to 404
`count5xx`	CountStatistic	Number of responses with a status code in the 5xx range
`count503`	CountStatistic	Number of responses with a status code equal to 503
`countother`	CountStatistic	Number of responses with other status codes
`errorcount`	CountStatistic	Number of responses with a status code greater than 400
`requests/seconds`	CountStatistic	Requests per second

JVM Statistics

The JVM fits into the tree of objects as show in JVM Tree Hierarchy.

The statistics that are available for the Virtual Machine for Java platform (Java^TM Virtual Machine) or JVM machine are shown in the following sections:

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, which is available from http://java.sun.com/javase/6/docs/technotes/guides/management/.

The Java SE monitoring tools are discussed at http://java.sun.com/javase/6/docs/technotes/tools/#manage.

The statistics that are available for class loading in the JVM for Java SE are shown in the following table.

Table 8–17 JVM Monitoring Statistics for Java SE Class Loading


Statistic	Data Type	Description
`loadedclasscount`	CountStatistic	Number of classes that are currently loaded in the JVM
`totalloadedclasscount`	CountStatistic	Total number of classes that have been loaded since the JVM began execution
`unloadedclasscount`	CountStatistic	Number of classes that have been unloaded from the JVM since the JVM began execution

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

Table 8–18 JVM Monitoring Statistics for Java SE - Threads


Statistic	Data Type	Description
`allthreadids`	StringStatistic	List of all live thread ids.
`currentthreadcputime`	CountStatistic	CPU time for the current thread (in nanoseconds) if CPU time measurement is enabled. If CPU time measurement is disabled, returns -1.
`daemonthreadcount`	CountStatistic	Current number of live daemon threads.
`monitordeadlockedthreads`	StringStatistic	List of thread ids that are monitor deadlocked.
`peakthreadcount`	CountStatistic	Peak live thread count since the JVM started or the peak was reset.
`threadcount`	CountStatistic	Current number of live daemon and non-daemon threads.
`totalstartedthreadcount`	CountStatistic	Total number of threads created and/or started since the JVM started.

JVM Compilation System Statistics

Use the following dotted name pattern for JVM compilation system statistics:

server.jvm.compilation-system.statistic

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

Table 8–19 JVM Monitoring Statistics for Java SE Compilation


Statistic	Data Type	Description
`name-current`	StringStatistic	Name of the current compiler
`totalcompilationtime`	CountStatistic	Accumulated time (in milliseconds) spent in compilation

JVM Garbage Collectors Statistics

Use the following dotted name pattern for JVM garbage collectors statistics:

server.jvm.garbage-collectors.statistic

The statistics that are available for garbage collection in the JVM for Java SE are shown in the following table.

Table 8–20 JVM Monitoring Statistics for Java SE Garbage Collectors


Statistic	Data Type	Description
`collectioncount`	CountStatistic	Total number of collections that have occurred
`collectiontime`	CountStatistic	Accumulated time (in milliseconds) spent in collection

JVM Memory Statistics

Use the following dotted name pattern for JVM memory statistics:

server.jvm.memory.statistic

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

Table 8–21 JVM Monitoring Statistics for Java SE Memory


Statistic	Data Type	Description
`committedheapsize`	CountStatistic	Amount of heap memory (in bytes) that is committed for the JVM to use
`committednonheapsize`	CountStatistic	Amount of non-heap memory (in bytes) that is committed for the JVM to use
`initheapsize`	CountStatistic	Size of the heap initially requested by the JVM
`initnonheapsize`	CountStatistic	Size of the non-heap area initially requested by the JVM
`maxheapsize`	CountStatistic	Maximum amount of heap memory (in bytes) that can be used for memory management
`maxnonheapsize`	CountStatistic	Maximum amount of non-heap memory (in bytes) that can be used for memory management
`objectpendingfinalizationcount`	CountStatistic	Approximate number of objects that are pending finalization
`usedheapsize`	CountStatistic	Size of the heap currently in use
`usednonheapsize`	CountStatistic	Size of the non-heap area currently in use

JVM Operating System Statistics

Use the following dotted name pattern for JVM operating system statistics:

server.jvm.operating-system.statistic

The statistics that are available for the operating system for the JVM machine in Java SE are shown in the following table.

Table 8–22 JVM Statistics for Java SE Operating System


Statistic	Data Type	Description
`arch-current`	StringStatistic	Operating system architecture
`availableprocessors`	CountStatistic	Number of processors available to the JVM
`name-current`	StringStatistic	Operating system name
`version-current`	StringStatistic	Operating system version

JVM Runtime Statistics

Use the following dotted name pattern for JVM runtime statistics:

server.jvm.runtime.statistic

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

Table 8–23 JVM Monitoring Statistics for Java SE Runtime


Statistic	Data Type	Description
`classpath-current`	StringStatistic	Classpath that is used by the system class loader to search for class files
`inputarguments-current`	StringStatistic	Input arguments passed to the JVM; not including arguments to the `main` method
`managementspecversion-current`	StringStatistic	Management specification version implemented by the JVM
`name-current`	StringStatistic	Name representing the running JVM
`specname-current`	StringStatistic	JVM specification name
`specvendor-current`	StringStatistic	JVM specification vendor
`specversion-current`	StringStatistic	JVM specification version
`uptime`	CountStatistic	Uptime of the JVM (in milliseconds)
`vmname-current`	StringStatistic	JVM implementation name
`vmvendor-current`	StringStatistic	JVM implementation vendor
`vmversion-current`	StringStatistic	JVM implementation version

Network Statistics

Network fits into the tree of objects as shown in Network Tree Hierarchy.

Network statistics are described in the following sections:

Network Keep Alive Statistics

Use the following dotted name pattern for network keep alive statistics:

server.network.type-of-listener.keep-alive.statistic

Statistics available for network keep alive are shown in the following table.

Table 8–24 Network Keep Alive Statistics


Statistic	Data Type	Description
`countconnections`	CountStatistic	Number of connections in keep-alive mode.
`counttimeouts`	CountStatistic	Number of keep-alive connections that timed out.
`secondstimeouts`	CountStatistic	Keep-alive timeout value in seconds.
`maxrequests`	CountStatistic	Maximum number of requests allowed on a single keep-alive connection.
`countflushes`	CountStatistic	Number of keep-alive connections that were closed.
`counthits`	CountStatistic	Number of requests received by connections in keep-alive mode.
`countrefusals`	CountStatistic	Number of keep-alive connections that were rejected.

Network Connection Queue Statistics

Use the following dotted name pattern for network connection queue statistics:

server.network.type-of-listener.connection-queue.statistic

Statistics available for network connection queue are shown in the following table.

Table 8–25 Network Connection Queue Statistics


Statistic	Data Type	Description
`countopenconnections`	CountStatistic	The number of open/active connections
`countoverflows`	CountStatistic	Number of times the queue has been too full to accommodate a connection
`countqueued`	CountStatistic	Number of connections currently in the queue
`countqueued15minutesaverage`	CountStatistic	Average number of connections queued in the last 15 minutes
`countqueued1minuteaverage`	CountStatistic	Average number of connections queued in the last 1 minute
`countqueued5minutesaverage`	CountStatistic	Average number of connections queued in the last 5 minutes
`counttotalconnections`	CountStatistic	Total number of connections that have been accepted
`counttotalqueued`	CountStatistic	Total number of connections that have been queued
`maxqueued`	CountStatistic	Maximum size of the connection queue
`peakqueued`	CountStatistic	Largest number of connections that were in the queue simultaneously
`tickstotalqueued`	CountStatistic	(Unsupported) Total number of ticks that connections have spent in the queue

Network File Cache Statistics

Use the following dotted name pattern for network file cache statistics:

server.network.type-of-listener.file-cache.statistic

Statistics available for network file cache are shown in the following table.

Table 8–26 Network File Cache Statistics


Statistic	Data Type	Description
`contenthits`	CountStatistic	Number of hits on cached file content
`contentmisses`	CountStatistic	Number of misses on cached file content
`heapsize`	CountStatistic	Current cache size in bytes
`hits`	CountStatistic	Number of cache lookup hits
`infohits`	CountStatistic	Number of hits on cached file info
`infomisses`	CountStatistic	Number of misses on cached file info
`mappedmemorysize`	CountStatistic	Size of mapped memory used for caching in bytes
`maxheapsize`	CountStatistic	Maximum heap space used for cache in bytes
`maxmappedmemorysize`	CountStatistic	Maximum memory map size used for caching in bytes
`misses`	CountStatistic	Number of cache lookup misses data type
`opencacheentries`	CountStatistic	Number of current open cache entries

Network Thread Pool Statistics

Use the following dotted name pattern for network thread pool statistics:

server.network.type-of-listener.thread-pool.statistic

Statistics available for network thread pool are shown in the following table.

Table 8–27 Network Thread Pool Statistics


Statistic	Data Type	Description
`corethreads`	CountStatistic	Core number of threads in the thread pool
`currentthreadcount`	CountStatistic	Provides the number of request processing threads currently in the listener thread pool
`currentthreadsbusy`	CountStatistic	Provides the number of request processing threads currently in use in the listener thread pool serving requests
`maxthreads`	CountStatistic	Maximum number of threads allowed in the thread pool
`totalexecutedtasks`	CountStatistic	Provides the total number of tasks, which were executed by the thread pool

ORB Statistics (Connection Manager)

The ORB fits into the tree of objects as shown in ORB Tree Hierarchy.

Use the following dotted name patterns for ORB statistics:

server.orb.transport.connectioncache.inbound.statistic
server.orb.transport.connectioncache.outbound.statistic

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.

The connection pool resources fit into the tree of objects as shown in Resources Tree Hierarchy.

Use the following dotted name pattern for connection pool statistics:

server.resources.connection-pool.statistic

The connection pool statistics are shown in the following table.

Table 8–29 Resource Monitoring Statistics (Connection Pool)


Statistic	Data Type	Description
`averageconnwaittime`	CountStatistic	Average wait-time-duration per successful connection request
`connrequestwaittime`	RangeStatistic	Longest and shortest wait times, in milliseconds, of connection requests since the last sampling. current value indicates the wait time of the last request that was serviced by the pool
`numconnfailedvalidation`	CountStatistic	Number of connections in the connection pool that failed validation from the start time until the last sampling time
`numconnused`	RangeStatistic	Number of connections that are currently being used, as well as information about the maximum number of connections that were used (high water mark)
`numconnfree`	RangeStatistic	Number of free connections in the pool as of the last sampling
`numconntimedout`	CountStatistic	Number of connections in the pool that timed out between the start time and the last sampling time
`numconncreated`	CountStatistic	Number of physical connections that were created by the pool since the last reset
`numconndestroyed`	CountStatistic	Number of physical connections that were destroyed since the last reset
`numconnacquired`	CountStatistic	Number of logical connections acquired from the pool since the last sampling
`numconnreleased`	CountStatistic	Number of connections released back to the pool since the last sampling
`numconnnotsuccessfullymatched`	CountStatistic	Number of connections rejected during matching
`numconnsuccessfullymatched`	CountStatistic	Number of connections successfully matched
`numpotentialconnleak`	CountStatistic	Number of potential connection leaks
`waitqueuelength`	CountStatistic	Number of connection requests in the queue waiting to be serviced

Security Statistics

Security fits into the tree of objects as shown in Security Tree Hierarchy.

Statistics available for security are shown in the following sections:

EJB Security Statistics

Use the following dotted name pattern for EJB security statistics:

server.security.ejb.statistic

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

Table 8–30 EJB Security Monitoring Statistics


Statistic	Data Type	Description
`policyconfigurationcount`	CountStatistic	Number of policy configuration
`securitymanagercount`	CountStatistic	Number of EJB security managers

Web Security Statistics

Use the following dotted name pattern for web security statistics:

server.security.web.statistic

The statistics available for web security are listed in the following table.

Table 8–31 Web Security Monitoring Statistics


Statistic	Data Type	Description
`websecuritymanagercount`	CountStatistic	Number of security managers
`webpolicyconfigurationcount`	CountStatistic	Number of policy configuration objects

Realm Security Statistics

Use the following dotted name pattern for realm security statistics:

server.security.realm.statistic

The statistics available for realm security are listed in the following table.

Table 8–32 Realm Security Monitoring Statistics


Statistic	Data Type	Description
`realmcount`	CountStatistic	Number of realms

Thread Pool Statistics

The thread pool fits into the tree of objects as shown in Thread Pool Tree Hierarchy.

The statistics available for thread pools are shown in the following sections:

Thread Pool Monitoring Statistics

Use the following dotted name pattern for thread pool statistics:

server.thread-pool.thread-pool.statistic

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.
`committedcount`	CountStatistic	Number of transactions that have been committed.
`rolledbackcount`	CountStatistic	Number of transactions that have been rolled back.
`state`	StringStatistic	Indicates whether or not the transaction has been frozen.

Web Statistics

The web module fits into the tree of objects as shown in Web Tree Hierarchy.

The available web statistics shown in the following sections:

Web Module Servlet Statistics

Use the following dotted name pattern for web module servlet statistics:

server.applications.web-module.virtual-server.servlet.statistic
server.applications.application.web-module.virtual-server.servlet.statistic

The available web module servlet statistics are shown in the following table.

Table 8–36 Web Module Servlet Statistics


Statistic	Data Type	Description
`errorcount`	CountStatistic	Cumulative number of cases where the response code is greater than or equal to 400.
`maxtime`	CountStatistic	Maximum amount of time the web container waits for requests.
`processingtime`	CountStatistic	Cumulative value of the amount of time required to process each request. The processing time is the average of request processing times divided by the request count.
`requestcount`	CountStatistic	The total number of requests processed so far.
`servicetime`	CountStatistic	Aggregate response time in milliseconds.

Web JSP Statistics

Use the following dotted name pattern for web JSP statistics:

server.applications.web-module.virtual-server.statistic
server.applications.application.web-module.virtual-server.statistic

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

Table 8–37 Web JSP Monitoring Statistics


Statistic	Data Type	Description
`jspcount-current`	RangeStatistic	Number of active JSP pages
`jsperrorcount`	CountStatistic	Total number of errors triggered by JSP page invocations
`jspreloadedcount`	CountStatistic	Total number of JSP pages that were reloaded
`totaljspcount`	CountStatistic	Total number of JSP pages ever loaded

Web Request Statistics

Use the following dotted name pattern for web request statistics:

server.applications.web-module.virtual-server.statistic
server.applications.application.web-module.virtual-server.statistic

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

Table 8–38 Web Request Monitoring Statistics


Statistic	Data Type	Description
`errorcount`	CountStatistic	Cumulative value of the error count, with error count representing the number of cases where the response code was greater than or equal to 400
`maxtime`	CountStatistic	Longest response time for a request; not a cumulative value, but the largest response time from among the response times
`processingtime`	CountStatistic	Average request processing time, in milliseconds
`requestcount`	CountStatistic	Cumulative number of the requests processed so far

Web Servlet Statistics

Use the following dotted name pattern for web servlet statistics:

server.applications.web-module.virtual-server.statistic
server.applications.application.web-module.virtual-server.statistic

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

Table 8–39 Web Servlet Monitoring Statistics


Statistic	Data Type	Description
`activeservletsloadedcount`	RangeStatistic	Number of currently loaded servlets
`servletprocessingtimes`	CountStatistic	Cumulative servlet processing times , in milliseconds
`totalservletsloadedcount`	CountStatistic	Cumulative number of servlets that have been loaded into the web module

Web Session Statistics

Use the following dotted name pattern for web session statistics:

server.applications.web-module.virtual-server.statistic
server.applications.application.web-module.virtual-server.statistic

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 Enterprise 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 Enterprise Server, Enterprise Server becomes the JMX Connector's server end and JConsole becomes the JMX connector's client end.

To Connect JConsole to Enterprise 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, Enterprise Server provides a configuration of the standard JMX connector server called System JMX Connector Server. As part of Enterprise 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, Enterprise 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.

Start the domain.

For instructions, see To Start a Domain.

Start JConsole using this format: JDK_HOME/bin/jconsole

For example:
/usr/java/bin/jconsole
The JConsole Connect to Agent window is displayed.

Click the Remote tab and type the host name and port.

Always connect remotely with JConsole, otherwise MBeans will not load automatically.

Click Connect.

In the Remote Process text box, specify the JMX Service URL.

For example:

service:jmx:rmi:///jndi/rmi://localhost:8686/jmxrmi

The JMX Service URL is emitted by the server at startup, looking something like this:

[#|2009-12-03T10:25:17.737-0800|INFO|glassfishv3.0|
javax.enterprise.system.tools.admin.org.glassfish.server|_ThreadID=20;
_ThreadName=Thread-26;|JMXStartupService: Started JMXConnector, JMXService 
URL = service:jmx:rmi://localhost:8686/jndi/rmi://localhost:8686/jmxrmi|#]

However, in most cases, simply entering host:port is fine, such as, 192.168.1.150:8686. The long Service URL is not needed.

Note –

Another host name can be substituted for localhost. The default port number (8686) could change if the jmx-connector configuration has been modified.

Click Connect.

In the JConsole window you will see all your MBeans, JVM information, and so on, in various tabs. Most of the useful MBeans are to be found in the amx and java.lang domains.

Chapter 9 Administering Life Cycle Modules

This chapter provides procedures for administering life cycle modules in the Sun GlassFish^TMEnterprise Server v3 environment.

The following topics are addressed here:

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

These events are defined in the LifecycleEvent class. For information on creating life cycle modules, see Chapter 13, Developing Lifecycle Listeners, in Sun GlassFish Enterprise Server v3 Application Development Guide.

Note –

If the is-failure-fatal setting is set to true (the default is false), life cycle module failure prevents server initialization or startup, but not shutdown or termination.

Configuring Life Cycle Modules

The following topics are addressed here:

To Create a Life Cycle Module

Use the create-lifecycle-module subcommand in remote mode to create a life cycle module.

Ensure that the server is running.

Remote subcommands require a running server.

Create a new life cycle modules by using the create-lifecycle-module(1) subcommand.

Information about options and properties for the subcommand are included in this help page.

Restart the server for your changes to take effect.

See To Restart a Domain.

Example 9–1 Creating a Life Cycle Module

This example creates the customSetup life cycle module :

asadmin> create-lifecycle-module --classname "com.acme.CustomSetup" 
--classpath "/export/customSetup" --loadorder 1 --failurefatal=true 
--description "this is a sample customSetup" 
--property rmi="Server\=acme1\:7070":timeout=30 customSetup
Command create-lifecycle-module executed successfully

To List Life Cycle Modules

Use the list-lifecycle-modules subcommand in remote mode to list the existing life cycle modules.

Ensure that the server is running.

Remote subcommands require a running server.

List life cycle modules by using the list-lifecycle-modules(1) subcommand.

Example 9–2 Listing Life Cycle Modules

This example lists the existing life cycle modules.

asadmin> list-lifecycle-modules
WSTCPConnectorLCModule
Command list-lifecycle-modules executed successfully

To Update a Life Cycle Module

Use the set subcommand to update an existing life cycle module.

List the properties that can be updated for a life cycle module by using the get(1) subcommand.

For example (single mode):

asadmin get "*" | grep sampleLCM
applications.application.sampleLCMmodule.availability-enabled=false
applications.application.sampleLCMmodule.directory-deployed=false
applications.application.sampleLCMmodule.enabled=true
applications.application.sampleLCMmodule.name=sampleLCMmodule
applications.application.sampleLCMmodule.object-type=user
applications.application.sampleLCMmodule.property.class-name=example.lc.SampleModule
applications.application.sampleLCMmodule.property.classpath=/build/lcm.jar
applications.application.sampleLCMmodule.property.is-failure-fatal=false
applications.application.sampleLCMmodule.property.isLifecycle=true

Update a life cycle module by using the set(1) subcommand.

Restart the server for your changes to take effect.

See To Restart a Domain.

Example 9–3 Updating a Life Cycle Module

This example updates the classpath property.

sadmin> set applications.application.sampleLCMmodule.
property.classpath=/build/lcm_new.jarapplications.application.
sampleLCMmodule.property.classpath=/build/lcm_new.jar
Command set executed successfully.

To Delete a Life Cycle Module

Use the delete-lifecycle-module subcommand in remote mode to delete a life cycle module.

Ensure that the server is running.

Remote subcommands require a running server.

List the current life cycle modules by using the list-lifecycle-modules(1) subcommand.

Delete a life cycle module by using the delete-lifecycle-module(1) subcommand.

Example 9–4 Deleting a Life Cycle Module

This example deletes the customSetup life cycle module.

asadmin> delete-lifecycle-module customSetup
Command delete-lifecycle-module executed successfully

Chapter 10 Extending Enterprise Server

This chapter provides procedures for performing tasks associated with extending and updating the deployed Sun GlassFish^TMEnterprise Server v3 by using Update Tool. Procedures for using the pkg command are contained in this chapter. A set of reference pages that contain details on using the pkg command is included with Enterprise Server.

The following topics are addressed here:

Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help for Update Tool. The standalone Update Tool also contains online help. For additional information about Update Tool, see http://wikis.sun.com/display/IpsBestPractices/Screenshots

About Add-on Components

Enterprise 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 Enterprise Server. You can add or remove an add-on component during runtime, with no need to restart the server.

Over time, new add-on components will be developed and existing components will be modified. Enterprise Server provides a set of image packaging system (IPS) tools for updating software on a deployed server. You can install new or updated add-on components by using the Update Tool in the following ways:

As a selection in the graphical Enterprise Server Administration Console
As a standalone graphical tool which can be started from the command line using the following format: as-install-parent/bin/updatetool
As a command-line utility (the pkg command) which can perform most of the tasks offered by the graphical Update Tool. The main reasons for using the pkg command are:
- As a basis for creating update scripts
- As a method for working with systems that do not have a monitor, graphic card, or keyboard (headless systems)

Extensive online help is provided for both graphical versions.

Adding Components

This section provides instructions for using the pkg command to install Enterprise Server add-on components on your deployed Enterprise 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 Enterprise Server, you will receive a query asking if you want to install the component. Answer Y to install the component.

Before You Begin

Enterprise Server v3 must be fully deployed before you can install additional components. If you need installation instructions, see Sun GlassFish Enterprise Server v3 Installation Guide.

List your installed components:

pkg list

Information similar to the following is displayed:

NAME (AUTHORITY)                              VERSION         STATE      UFIX
glassfishv3-common                            0-1             installed  ----
glassfishv3-ejb                               0-1             installed  u---
glassfishv3-nucleus                           0-1             installed  ----
glassfishv3-web                               0-1             installed  ----
grails                                        1.0-1.0         installed  ----
jersey                                        0.7-0.1         installed  u---
jmaki                                         1.8.0-1.0       installed  ----
jruby                                         1.1.1-1.0       installed  ----
metro                                         1.2-1           installed  u---
pkg                                           0.1.4-6.564     installed  u---
python2.4-minimal                             2.4.4-6.564     installed  u---
updatetool (glassfish.org)                    2.0-6.564       installed  u---
wxpython2.8-minimal                           2.8.7.1-6.564   installed  u---

List all packages that are available:

pkg list -a

Information similar to the following is displayed from the repository:

NAME (AUTHORITY)                              VERSION         STATE      UFIX
glassfishv3-common                            0-1             known      u---
glassfishv3-common                            0-1             known      u---
glassfishv3-common                            0-1             installed  ----
glassfishv3-ejb                               0-1             known      u---
glassfishv3-ejb                               0-1             known      u---
glassfishv3-ejb                               0-1             known      u---
glassfishv3-ejb                               0-1             installed  u---
glassfishv3-ejb                               0-1             known      ----
glassfishv3-nucleus                           0-1             known      u---
glassfishv3-nucleus                           0-1             known      u---
glassfishv3-nucleus                           0-1             installed  ----
glassfishv3-web                               0-1             known      u---
glassfishv3-web                               0-1             known      u---
glassfishv3-web                               0-1             installed  ----
grails                                        1.0-1.0         installed  ----
javadb                                        0-1             known      u---
javadb                                        0-1             known      u---
javadb                                        0-1             known      ----
jersey                                        0.7-0.1         installed  u---
jersey                                        0.7-0.2         known      u---
jersey                                        0.7-0.3         known      u---
jersey                                        0.8-0.1         known      ----
jmaki                                         1.8.0-1.0       installed  ----
jruby                                         1.1.1-1.0       installed  ----
metro                                         1.2-1           installed  u---
metro                                         1.2-2           known      u---
metro                                         1.2-3           known      ----
pkg                                           0.1.4-6.564     installed  u---
pkg                                           0.1.5-8.724     known      ----
python2.4-minimal                             2.4.4-6.564     installed  u---
python2.4-minimal                             2.4.4-8.724     known      ----
updatetool                                    2.0-6.564       installed  u---
updatetool                                    2.0-8.724       known      ----
wxpython2.8-minimal                           2.8.7.1-6.564   installed  u---
wxpython2.8-minimal                           2.8.7.1-8.724   known      ----

Navigate to the as-install directory.

Install a package from the available packages list.

Use the following syntax: pkg install package-name. For example:

pkg install javadb

The most recent version of the component is installed and information similar to the following is displayed:

DOWNLOAD                                     PKGS       FILES     XFER (MB)
javadb                                       0/1      61/200     2.10/7.26 

PHASE                                        ACTIONS
Install Phase                                222/222

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

Updating Installed Components

This section provides the following instructions for updating Enterprise Server components after they have been installed:

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.

Obtain a list of only the installed packages that have available updates:

pkg list -u

Information similar to the following is displayed:

NAME (AUTHORITY)                              VERSION         STATE      UFIX
glassfishv3-ejb                               0-1             installed  u---
jersey                                        0.7-0.1         installed  u---
metro                                         1.2-1           installed  u---
pkg                                           0.1.4-6.564     installed  u---
python2.4-minimal                             2.4.4-6.564     installed  u---
updatetool (glassfish.org)                    2.0-6.564       installed  u---
wxpython2.8-minimal                           2.8.7.1-6.564   installed  u---

Install a new version of a package.

Use the following syntax: pkg install package-name. For example:

pkg install metro

Information similar to the following is displayed:

DOWNLOAD                                     PKGS       FILES     XFER (MB)
Completed                                    1/1         5/5     0.49/0.49 

PHASE                                        ACTIONS
Removal Phase                                    2/2 
Update Phase                                     7/7 
Install Phase                                    2/2

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

To Update All Installed Components in an Image

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

Install all packages for the image.

Use the following syntax: pkg install image-name. For example:

pkg image-update

Information similar to the following is displayed:

DOWNLOAD                                     PKGS       FILES     XFER (MB)
Completed                                    6/6     729/729   21.59/21.59 

PHASE                                        ACTIONS

Removal Phase                                887/887 
Update Phase                                 253/253 
Install Phase                                584/584

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

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.

To Uninstall an Installed Component

Before You Begin

Verify that there are no dependencies on the installed component before removing it.

Obtain a list of all your installed components:

pkg list

NAME (AUTHORITY)                              VERSION         STATE      UFIX
glassfishv3-common                            0-1             installed  ----
glassfishv3-ejb                               0-1             installed  u---
glassfishv3-nucleus                           0-1             installed  ----
glassfishv3-web                               0-1             installed  ----
grails                                        1.0-1.0         installed  ----
jersey                                        0.7-0.1         installed  u---
jmaki                                         1.8.0-1.0       installed  ----
jruby                                         1.1.1-1.0       installed  ----
metro                                         1.2-1           installed  u---
pkg                                           0.1.4-6.564     installed  u---
python2.4-minimal                             2.4.4-6.564     installed  u---
updatetool (glassfish.org)                    2.0-6.564       installed  u---
wxpython2.8-minimal                           2.8.7.1-6.564   installed  u---

Uninstall the component that you want removed from your system.

Use the following syntax: pkg uninstall package-name. For example:
pkg uninstall jruby

To apply your changes, restart Enterprise Server.

See To Restart a Domain.

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.

Verify that the older version of the component is still available:
pkg list -a

Obtain a list of your installed components:
pkg list

Uninstall the currently-installed component that you want to replace.

Use the following syntax: pkg uninstall package-name. For example:
pkg uninstall jersey

Install the older version of the component.

Use the following syntax: pkg install package-name —version version-number. For example:
pkg install jersey -version 0.7-0.2

Verify that the older version is installed:
pkg list

Part I Runtime Administration

Chapter 2 General Administration

Using the asadmin Utility

Path to the asadmin Utility

asadmin Utility Syntax

Subcommands of the asadmin Utility

asadmin Utility Options and Subcommand Options

Operands of asadmin Utility Subcommands

To Run an asadmin Utility Subcommand in Single Mode

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

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

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

To Display Help Information for the asadmin Utility or a Subcommand

Example 2–4 Displaying Help Information for the asadmin Utility

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

See Also

To Start a Multimode Session

Example 2–6 Starting a Multimode Session With asadmin Utility Options

Example 2–7 Starting a Multimode Session by Using the multimode Subcommand

Example 2–8 Running a Subcommand in a Multimode Session

Starting a Multimode Session From Within an Existing Multimode Session

See Also

To End a Multimode Session

To Run a Set of asadmin Subcommands From a File

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

See Also

Administering System Properties

To Create System Properties

Example 2–10 Creating a System Property

See Also

To List System Properties

Example 2–11 Listing System Properties

See Also

To Delete a System Property

Example 2–12 Deleting a System Property

See Also

Administering Resources

To Add Resources From an XML File

Example 2–13 Adding Resources

See Also

Listing Various System Elements

To Display the Enterprise Server Version

Example 2–14 Displaying Version Information

See Also

To List Applications

Example 2–15 Listing Applications

See Also

To List Containers

Example 2–16 Listing Containers

See Also

To List Modules

Example 2–17 Listing Modules

See Also

To List Subcommands

Example 2–18 Listing Subcommands

See Also

To List Timers

Example 2–19 Listing Timers

To Show Component Status

Example 2–20 Showing Status of a Component

Using REST Interfaces to Administer Enterprise Server

Using REST URLs to Administer Enterprise Server

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

Using REST Resource Methods to Administer Enterprise Server

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

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

To Retrieve Data for a Node in the Tree

Example 2–22 Retrieving Data for a Node in the Tree

To Add a Node to the Tree

Example 2–23 Adding a Node to the Tree

To Update a Node in the Tree

Example 2–24 Updating a Node in the Tree

To Delete a Node From the Tree

Example 2–25 Deleting a Node From the Tree

Child Resources for Non-CRUD Operations

Securing Enterprise Server REST Interfaces

Formats for Resource Representation

JSON Resource Representation

JSON Representation of a Method in a Method List

JSON Representation of a Message Parameter or a Query Parameter

Using the `asadmin` Utility

Path to the `asadmin` Utility

`asadmin` Utility Syntax

Subcommands of the `asadmin` Utility

`asadmin` Utility Options and Subcommand Options

Operands of `asadmin` Utility Subcommands

To Run an `asadmin` Utility Subcommand in Single Mode

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

Example 2–2 Specifying an `asadmin` Utility Option With a Subcommand in Single Mode

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

To Display Help Information for the `asadmin` Utility or a Subcommand

Example 2–4 Displaying Help Information for the `asadmin` Utility

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

Example 2–6 Starting a Multimode Session With `asadmin` Utility Options

Example 2–7 Starting a Multimode Session by Using the `multimode` Subcommand

To Run a Set of `asadmin` Subcommands From a File

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