Part I Runtime Administration

Chapter 2 General Administration

This chapter provides instructions for performing general administration tasks in the Oracle GlassFish Server 3.0.1 environment by using the asadmin command-line utility.

The following topics are addressed here:

• Using the asadmin Utility

• Administering System Properties

• Administering Resources

• Listing Various System Elements

• Using REST Interfaces to Administer GlassFish Server

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

• asadmin Utility Syntax

• To Run an asadmin Utility Subcommand in Single Mode

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

• To Start a Multimode Session

• To End a Multimode Session

• To Run a Set of asadmin Subcommands From a File

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 GlassFish Server, see Section 1 of Oracle GlassFish Server 3.0.1 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 Oracle GlassFish Server 3.0.1 Reference Manual.

  ---

  Note –

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

  ---

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

Options have a long form and a short form.

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

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

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

• Short form: -t

• Long form: --terse

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

Operands of asadmin Utility Subcommands

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

To Run an asadmin Utility Subcommand in Single Mode

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

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

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

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

   Remote subcommands require a running server.

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

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

Example 2–4 Displaying Help Information for the asadmin Utility

This example displays the help information for the asadmin utility.

asadmin help

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

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

asadmin help create-jdbc-resource

See Also

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

To Start a Multimode Session

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

Starting a multimode session does not require a running DAS.

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

See Also

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

To End a Multimode Session

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

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

2. 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:

1. Creating the domain customdomain

2. Starting the domain customdomain

3. Listing all available subcommands

4. Stopping the domain customdomain

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

See Also

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

• create-domain(1)

• delete-domain(1)

• list-commands(1)

• multimode(1)

• start-domain(1)

• stop-domain(1)

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

• To List System Properties

• To Delete a System Property

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.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

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.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

To Delete a System Property

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

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

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

See Also

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

Administering Resources

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

To Add Resources From an XML File

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

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

3. Restart GlassFish 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.

See Also

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

Listing Various System Elements

The following topics are addressed here:

• To Display the GlassFish Server Version

• To List Applications

• To List Containers

• To List Modules

• To List Subcommands

• To List Timers

• To Show Component Status

To Display the GlassFish Server Version

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

Example 2–14 Displaying Version Information

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

asadmin> version
Version = Oracle GlassFish Server 3.0.1 (build 19)
Command version executed successfully.

See Also

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

To List Applications

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

To List Containers

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

To List Modules

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

To List Subcommands

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

To List Timers

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

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. 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 GlassFish Server

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

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

• Web browsers

• cURL

• GNU Wget

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

• JavaScript

• Ruby

• Perl

• Java

• JavaFX

The implementation of the GlassFish Server REST interfaces is based on project Jersey. Project Jersey is the reference implementation of Java 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 GlassFish Server

• Using REST Resource Methods to Administer GlassFish Server

• Child Resources for Non-CRUD Operations

• Securing GlassFish Server REST Interfaces

• Formats for Resource Representation

Using REST URLs to Administer GlassFish Server

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

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

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

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

The replaceable items in these URLs are as follows:

host

The host where the DAS is running.

port

The HTTP port or HTTPS port for administration.

path

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

• The dotted-names(5ASC) help page

• How the Monitoring Tree Structure Works

• How Dotted Names Work for Configuration

• Element Hierarchy in Oracle GlassFish Server 3.0.1 Domain File Format Reference

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

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

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

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

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

Using REST Resource Methods to Administer GlassFish Server

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

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

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.

1. Ensure that the server is running.

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

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

1. Ensure that the server is running.

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

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

1. Ensure that the server is running.

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

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

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

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

1. 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" } } }

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

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

1. Ensure that the server is running.

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

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

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

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

1. 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"} } } } }

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

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

1. Ensure that the server is running.

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

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

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

1. 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"} } } } }

2. This step deletes the jdbc-myjdbcresource resource.

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

3. 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 GlassFish Server REST interfaces also support operations other than create, read, update, and delete (CRUD) operations, for example:

• State management

• Queries

• Application deployment

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

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

Securing GlassFish Server REST Interfaces

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

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

1. Adding an admin-realm user to the asadmin user group

2. Enabling Secure Sockets Layer (SSL)

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

• To Create an Authentication Realm

• To Create a File User

• To Configure an HTTP Listener for SSL

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 GlassFish 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 GlassFish Server REST interfaces. For example, if you are using the cURL utility, specify the resource representation through the -H option as follows:

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

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

• For HTML, omit the -H option.

JSON Resource Representation

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

{
    "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 Oracle GlassFish Server 3.0.1 environment by using the asadmin command-line utility.

The following topics are addressed here:

• About Administering Domains (or Servers)

• Creating, Logging In To, and Deleting a Domain

• Starting and Stopping a Domain

• Configuring a Domain for Automatic Restart

• Additional Domain Tasks

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

About Administering Domains (or Servers)

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

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

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

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

Creating, Logging In To, and Deleting a Domain

The following topics are addressed here:

• To Create a Domain

• To List Domains

• To Log In to a Domain

• To Delete a Domain

To Create a Domain

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

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

Before You Begin

Determine which profile will apply to the domain.

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

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

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

3. 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=Oracle Corp.,L=Redwood Shores,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

See Also

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

To List Domains

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

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

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

See Also

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

To Log In to a Domain

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

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

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

• The server (domain) uses file realm for authentication of administrative users.

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

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

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

• That one user has no password.

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

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

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

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

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

   To list the existing domains:

   asadmin list-domains

2. Log in to the domain by using the login(1)command.

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

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

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

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

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

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

See Also

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

To Delete a Domain

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

Before You Begin

A domain must be stopped before it can be deleted.

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

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

3. Ensure that the domain you want to delete is stopped.

   If needed, see To Stop a Domain.

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

See Also

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

Starting and Stopping a Domain

The following topics are addressed here:

• To Start a Domain

• To Stop a Domain

• To Restart a Domain

To Start a Domain

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

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

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

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

• If you are using the Web Profile, select Programs -> Oracle GlassFish Server Web Profile -> Start Admin Server.

This subcommand is supported in local mode only.

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

See Also

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

To Stop a Domain

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

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

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

• If you are using the Web Profile, select Programs -> Oracle GlassFish Server Web Profile -> Stop Admin Server.

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

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

See Also

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

To Restart a Domain

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

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

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

Configuring a Domain for Automatic Restart

This section provides instructions for configuring your system to automatically restart a domain .

The following topics are addressed here:

• To Configure a Domain for Automatic Restart on Windows

• To Configure a Domain for Automatic Restart on Oracle Solaris 10

• To Restart Automatically on Linux

• To Prevent Service Shutdown When a User Logs Out on Windows

To Configure a Domain for Automatic Restart on Windows

On Windows, you can use the asadmin create-service subcommand to create a Windows service that restarts a Domain Administration Server (DAS).

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

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

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

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

Example 3–10 Creating a Service on a Windows System

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

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

This message is also available in a file named PlatformServices.log in the domain's 
root directory
Command create-service executed successfully.

To Configure a Domain for Automatic Restart on Oracle Solaris 10

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

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

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

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

Before You Begin

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

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

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

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

   For example:

   svacdm enable /appserver/domains/domain1

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

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

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

See Also

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

To Restart Automatically on Linux

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

1. 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 a User Logs Out on Windows

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

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

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

Additional Domain Tasks

The following topics are addressed here:

• To Display Domain Uptime

• To Switch a Domain to Another Supported Java Version

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.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Display uptime by using the uptime(1) subcommand.

Example 3–12 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.

See Also

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

To Switch a Domain to Another Supported Java Version

GlassFish Server 3.0.1 requires Version 6 Java SE platform as the underlying virtual machine for the Java platform (Java Virtual Machine or JVM machine).

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.

1. 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 the Java SE Downloads page.

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

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

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

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

Chapter 4 Administering the Virtual Machine for the Java Platform

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

The following topics are addressed here:

• Administering JVM Options

• Administering the Profiler

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

Administering JVM Options

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

The following topics are addressed here:

• To Create JVM Options

• To List JVM Options

• To Delete JVM Options

• To Generate a JVM Report

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.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

3. To apply your changes, restart GlassFish 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.

See Also

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

To List JVM Options

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

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.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

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

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

5. To apply your changes, restart GlassFish 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.

See Also

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

To Generate a JVM Report

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

Administering the Profiler

A profiler generates information used to analyze server performance.

The following topics are addressed here:

• To Create a Profiler

• To Delete a Profiler

To Create a Profiler

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

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

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

3. To apply your changes, restart GlassFish 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.

See Also

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

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.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

3. To apply your changes, restart GlassFish 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.

See Also

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

Chapter 5 Administering Thread Pools

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

The following topics are addressed here:

• About Thread Pools

• Configuring Thread Pools

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

About Thread Pools

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

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

Configuring Thread Pools

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

The following topics are addressed here:

• To Create a Thread Pool

• To List Thread Pools

• To Update a Thread Pool

• To Delete a Thread Pool

To Create a Thread Pool

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

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

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

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

3. To apply your changes, restart GlassFish 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

See Also

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

To List Thread Pools

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

To Update a Thread Pool

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

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

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

   The thread pool is identified by its dotted name.

3. To apply your changes, restart GlassFish 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

See Also

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

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.

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

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

4. To apply your changes, restart GlassFish 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

See Also

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

Chapter 6 Administering Web Applications

This chapter explains how to administer web applications in the Oracle GlassFish Server 3.0.1 environment.

The following topics are addressed here:

• Invoking a Servlet by Alternate Means

• Changing Log Output for a Servlet

• Defining Global Features for Web Applications

• Redirecting a URL

• Administering mod_jk

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

Invoking a Servlet by Alternate Means

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

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

The following table describes each URL section.

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

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

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

3. To apply your changes, restart GlassFish 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 GlassFish Server, you can front GlassFish Server with Apache HTTP Server.

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

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

The following topics are addressed here:

• To Enable mod_jk

• To Load Balance Using mod_jk and GlassFish Server

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

• To Enable SSL Between the mod_jk Load Balancer and GlassFish Server

To Enable mod_jk

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

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

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

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

3. Start Apache HTTP Server (httpd).

4. Start GlassFish 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.

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

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

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

8. To apply your changes, restart GlassFish 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

See Also

For more information on Apache, see http://httpd.apache.org/.

For more information on Apache Tomcat Connector, see http://tomcat.apache.org/connectors-doc/index.html.

To Load Balance Using mod_jk and GlassFish Server

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

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

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

2. On each of the instances, create the jvmRoute system property of GlassFish 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.

3. To apply your changes, restart Apache HTTP Server and GlassFish 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 GlassFish Server, you must first generate a Secure Socket Layer (SSL) self-signed certificate on the Apache HTTP Server with the mod_ssl module. The tasks include generating a private key, a Certificate Signing Request (CSR), a self-signed certificate, and configuring SSL-enabled virtual hosts.

Before You Begin

The mod_jk connector must be enabled.

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

2. Remove the pass-phrase from the key as follows:

   openssl rsa -in server.key -out server.pem

3. Generate the CSR is as follows:

   openssl req -new -key server.pem -out server.csr

   Enter the information you are prompted for.

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

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

6. 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 GlassFish Server

Before You Begin

The self-signed certificate must be configured.

1. Perform the steps in To Enable mod_jk.

2. Start another GlassFish 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.

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

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

5. To apply your changes, restart Apache HTTP Server and GlassFish Server.

Chapter 7 Administering the Logging Service

This chapter provides instructions on how to configure logging and how to view log information in the Oracle GlassFish Server 3.0.1 environment.

The following topics are addressed here:

• About Logging

• Setting Log Levels

• Rotating the Server Log

• Changing the Limit on the Number of Rotated Log Files

• Viewing Log Information

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

About Logging

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

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

The following topics are addressed here:

• Log File

• Logger Namespaces

Log File

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

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

• HTTP service access logs, located in the /access subdirectory

• Transaction service logs, located in the /tx subdirectory

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

GlassFish 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 GlassFish 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 GlassFish Server SEVERE and WARNING messages and for many INFO messages, the message begins with a message ID that consists of a module code and a numerical value. For example: CORE5004

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

The following topics are addressed here:

• To List the Logger Levels

• To Set the Global Log Level

• To Set Module Logger Levels

To List the Logger Levels

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

To Set the Global Log Level

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

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

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

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

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

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

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

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

See Also

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

Rotating the Server Log

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

To Rotate a Log File Manually

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

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

1. Ensure that the server is running.

   Remote subcommands require a running server.

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

See Also

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

Changing the Limit on the Number of Rotated Log Files

When GlassFish Server rotates a log file, it creates a new, empty file named server.log and renames the old file server.log_date, where date is the date and time when the file was rotated.

By default, GlassFish Server limits the number of rotated log files to 10. When this limit is reached, the oldest log file is deleted when GlassFish Server next rotates a log file.

If necessary, you can change the limit on the number of rotated log files. Any new limit that you set applies to rotated log files for both access logging and the server log.

To Change the Limit on the Number of Rotated Log Files

You can change the limit on the number of rotated log files by using the create-system-properties subcommand in remote mode to set a system property.

1. Ensure that the server is running.

   Remote subcommands require a running server.

2. Use the create-system-properties(1) subcommand to set the com.sun.enterprise.server.logging.max_history_files system property to the maximum number of rotated log files to keep.

   The behavior of the com.sun.enterprise.server.logging.max_history_files system property is as follows:

   • If the property is not set, GlassFish Server keeps a maximum of 10 rotated log files.

   • If the property is set to an invalid number or null, GlassFish Server keeps a maximum of 10 rotated log files.

   • If the property is set to 0, GlassFish Server keeps no rotated log files.

Example 7–6 Changing the Limit on the Number of Rotated Log Files

This example changes the limit on the number of rotated log files to 5.

asadmin> create-system-properties 
com.sun.enterprise.server.logging.max_history_files=5

Command create-system-properties executed successfully.

Viewing Log Information

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

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

Chapter 8 Administering the Monitoring Service

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

The following topics are addressed here:

• About Monitoring

• Configuring Monitoring

• Viewing Common Monitoring Data

• Viewing Comprehensive Monitoring Data

• Configuring JConsole to View GlassFish Server Monitoring Data

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 GlassFish 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 GlassFish Server, you can identify performance bottlenecks, predict failures, perform root cause analysis, and ensure that everything is functioning as expected. Data gathered by monitoring can also be useful in performance tuning and capacity planning.

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

The following topics are addressed here:

• How the Monitoring Tree Structure Works

• About Monitoring for Add-on Components

• Tools for Monitoring GlassFish Server

How the Monitoring Tree Structure Works

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

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

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

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

• Connector Service Tree Hierarchy

• HTTP Service Tree Hierarchy

• JMS/Container Service Tree Hierarchy

• JRuby Tree Hierarchy

• JVM Tree Hierarchy

• Network Tree Hierarchy

• ORB Tree Hierarchy

• Resources Tree Hierarchy

• Security Tree Hierarchy

• Thread Pool Tree Hierarchy

• Transactions Service Tree Hierarchy

• Web Tree Hierarchy

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

Tools for Monitoring GlassFish Server

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

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

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

• The 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 GlassFish Server, but monitoring for the individual modules is not. To enable monitoring for a module, you change the monitoring level for that module to LOW or HIGH, You can choose to leave monitoring OFF for objects that do not need to be monitored.

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

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

• OFF. No monitoring, no impact on performance

The following tasks are addressed here:

• To Enable Monitoring

• To Disable Monitoring

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

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

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

See Also

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

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

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

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

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

See Also

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

Viewing Common Monitoring Data

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

• To View Common Monitoring Data

• Common Monitoring Statistics

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.

1. Determine which type of monitorable object you want to monitor.

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

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

See Also

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

Common Monitoring Statistics

Common monitoring statistics are described in the following sections:

• HTTP Listener Common Statistics

• JVM Common Statistics

• Web Module Common Statistics

HTTP Listener Common Statistics

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

JVM Common Statistics

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

Web Module Common Statistics

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

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

• To View Comprehensive Monitoring Data

• Comprehensive Monitoring Statistics

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.

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.

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

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

• HTTP Service Statistics

• Jersey Statistics

• JMS/Connector Service Statistics

• JRuby Statistics

• JVM Statistics

• Network Statistics

• ORB Statistics (Connection Manager)

• Resource Statistics (Connection Pool)

• Security Statistics

• Thread Pool Statistics

• Transaction Service Statistics

• Web Statistics

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

• EJB Container Statistics

• EJB Method Statistics

• EJB Pool Statistics

• Timer Statistics

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.

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.

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.

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.

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.

HTTP Service Statistics

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

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.

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.

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)

• Connector Work Management Statistics (JMS)

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.

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.

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

• JRuby Runtime Statistics

• JRuby HTTP Service Statistics

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.

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.

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.

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 Virtual Machine) or JVM machine are shown in the following sections:

• JVM Class Loading System Statistics

• JVM Compilation System Statistics

• JVM Garbage Collectors Statistics

• JVM Memory Statistics

• JVM Operating System Statistics

• JVM Runtime Statistics

JVM Class Loading System Statistics

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

server.jvm.class-loading-system.statistic

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

The Java SE monitoring tools are discussed at http://download.oracle.com/docs/cd/E17409_01/javase/6/docs/technotes/tools/.

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

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

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.

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.

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.

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.

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.

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

• Network Connection Queue Statistics

• Network File Cache Statistics

• Network Thread Pool Statistics

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.

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.

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.

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.

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.

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.

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

• Web Security Statistics

• Realm Security Statistics

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.

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.

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.

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

• JVM Statistics for Java SE-Thread Information

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.

JVM Statistics for Java SE-Thread Information

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