Eclipse GlassFish
Administration Guide
Release 7
Contributed 2018 - 2024
Eclipse GlassFish 7 Administration Guide provides instructions for configuring and administering Eclipse GlassFish.
Eclipse GlassFish Administration Guide, Release 7
Copyright © 2013, 2019 Oracle and/or its affiliates. All rights reserved.
This program and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0, which is available at http://www.eclipse.org/legal/epl-2.0.
SPDX-License-Identifier: EPL-2.0
Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.
Preface
The Eclipse GlassFish Administration Guide provides instructions for configuring and administering Eclipse GlassFish.
This preface contains information about and conventions for the entire Eclipse GlassFish (Eclipse GlassFish) documentation set.
Eclipse GlassFish 7 is developed through the GlassFish project open-source community at https://github.com/eclipse-ee4j/glassfish. The GlassFish project provides a structured process for developing the Eclipse GlassFish platform that makes the new features of the Jakarta EE platform available faster, while maintaining the most important feature of Jakarta EE: compatibility. It enables Java developers to access the Eclipse GlassFish source code and to contribute to the development of the Eclipse GlassFish.
The following topics are addressed here:
Eclipse GlassFish Documentation Set
The Eclipse GlassFish documentation set describes deployment planning and system installation. For an introduction to Eclipse GlassFish, refer to the books in the order in which they are listed in the following table.
Book Title | Description |
---|---|
Provides late-breaking information about the software and the documentation and includes a comprehensive, table-based summary of the supported hardware, operating system, Java Development Kit (JDK), and database drivers. |
|
Explains how to get started with the Eclipse GlassFish product. |
|
Explains how to install the software and its components. |
|
Explains how to upgrade to the latest version of Eclipse GlassFish. This guide also describes differences between adjacent product releases and configuration options that can result in incompatibility with the product specifications. |
|
Explains how to build a production deployment of Eclipse GlassFish that meets the requirements of your system and enterprise. |
|
Explains how to configure, monitor, and manage Eclipse GlassFish subsystems and components
from the command line by using the |
|
Provides instructions for configuring and administering Eclipse GlassFish security. |
|
Explains how to assemble and deploy applications to the Eclipse GlassFish and provides information about deployment descriptors. |
|
Explains how to create and implement Java Platform, Enterprise Edition (Jakarta EE platform) applications that are intended to run on the Eclipse GlassFish. These applications follow the open Java standards model for Jakarta EE components and application programmer interfaces (APIs). This guide provides information about developer tools, security, and debugging. |
|
Explains how to use published interfaces of Eclipse GlassFish to develop add-on components for Eclipse GlassFish. This document explains how to perform only those tasks that ensure that the add-on component is suitable for Eclipse GlassFish. |
|
Explains how to run applications in embedded Eclipse GlassFish and to develop applications in which Eclipse GlassFish is embedded. |
|
Explains how to configure Eclipse GlassFish to provide higher availability and scalability through failover and load balancing. |
|
Explains how to optimize the performance of Eclipse GlassFish. |
|
Describes common problems that you might encounter when using Eclipse GlassFish and explains how to solve them. |
|
Describes error messages that you might encounter when using Eclipse GlassFish. |
|
Provides reference information in man page format for Eclipse GlassFish administration commands, utility commands, and related concepts. |
|
Describes new features, compatibility issues, and existing bugs for Open Message Queue. |
|
Provides an introduction to the technology, concepts, architecture, capabilities, and features of the Message Queue messaging service. |
|
Explains how to set up and manage a Message Queue messaging system. |
|
Describes the application programming interface in Message Queue for programmatically configuring and monitoring Message Queue resources in conformance with the Java Management Extensions (JMX). |
|
Provides information about concepts and procedures for developing Java messaging applications (Java clients) that work with Eclipse GlassFish. |
|
Provides programming and reference information for developers working with Message Queue who want to use the C language binding to the Message Queue messaging service to send, receive, and process Message Queue messages. |
Related Documentation
The following tutorials explain how to develop Jakarta EE applications:
-
Your First Cup: An Introduction to the Jakarta EE Platform. For beginning Jakarta EE programmers, this short tutorial explains the entire process for developing a simple enterprise application. The sample application is a web application that consists of a component that is based on the Enterprise JavaBeans specification, a JAX-RS web service, and a JavaServer Faces component for the web front end.
-
The Jakarta EE Tutorial. This comprehensive tutorial explains how to use Jakarta EE platform technologies and APIs to develop Jakarta EE applications.
Javadoc tool reference documentation for packages that are provided with Eclipse GlassFish is available as follows.
-
The Jakarta EE specifications and API specification is located at https://jakarta.ee/specifications/.
-
The API specification for Eclipse GlassFish 7, including Jakarta EE platform packages and nonplatform packages that are specific to the Eclipse GlassFish product, is located at https://glassfish.org/docs/.
For information about creating enterprise applications in the NetBeans Integrated Development Environment (IDE), see the NetBeans Documentation, Training & Support page.
For information about the Derby database for use with the Eclipse GlassFish, see the Derby page.
The Jakarta EE Samples project is a collection of sample applications that
demonstrate a broad range of Jakarta EE technologies. The Jakarta EE Samples
are bundled with the Jakarta EE Software Development Kit (SDK) and are also
available from the repository
(https://github.com/eclipse-ee4j/glassfish-samples
).
Typographic Conventions
The following table describes the typographic changes that are used in this book.
Typeface | Meaning | Example |
---|---|---|
|
The names of commands, files, and directories, and onscreen computer output |
Edit your Use
|
|
What you type, contrasted with onscreen computer output |
|
AaBbCc123 |
A placeholder to be replaced with a real name or value |
The command to remove a file is |
AaBbCc123 |
Book titles, new terms, and terms to be emphasized (note that some emphasized items appear bold online) |
Read Chapter 6 in the User’s Guide. A cache is a copy that is stored locally. Do not save the file. |
Symbol Conventions
The following table explains symbols that might be used in this book.
Symbol | Description | Example | Meaning |
---|---|---|---|
|
Contains optional arguments and command options. |
|
The |
|
Contains a set of choices for a required command option. |
|
The |
|
Indicates a variable reference. |
|
References the value of the |
|
Joins simultaneous multiple keystrokes. |
Control-A |
Press the Control key while you press the A key. |
|
Joins consecutive multiple keystrokes. |
Ctrl+A+N |
Press the Control key, release it, and then press the subsequent keys. |
|
Indicates menu item selection in a graphical user interface. |
File > New > Templates |
From the File menu, choose New. From the New submenu, choose Templates. |
Default Paths and File Names
The following table describes the default paths and file names that are used in this book.
Placeholder | Description | Default Value |
---|---|---|
as-install |
Represents the base installation directory for Eclipse GlassFish.
In configuration files, as-install is represented as follows:
|
|
as-install-parent |
Represents the parent of the base installation directory for Eclipse GlassFish. |
|
domain-root-dir |
Represents the directory in which a domain is created by default. |
as-install |
domain-dir |
Represents the directory in which a domain’s configuration is stored.
In configuration files, domain-dir is represented as follows:
|
domain-root-dir/domain-name |
instance-dir |
Represents the directory for a server instance. |
domain-dir/instance-name |
1 Overview of Eclipse GlassFish Administration
Eclipse GlassFish provides a server for developing and deploying Java Platform Enterprise Edition (Jakarta EE) applications and web Java Web Services.
As an administrator ofEclipse GlassFish, your main responsibilities are to establish a secure Eclipse GlassFish environment and to oversee the services, resources, and users that participate in that environment. Your key tasks include configuring resources and services, managing Eclipse GlassFish at runtime, and fixing problems that are associated with the server. You might also be involved in installing software, integrating add-on components, and deploying applications.
The following topics are addressed here:
Default Settings and Locations
After installation, you might need to perform some immediate configuration tasks to make your installation function as intended. If configuration defaults have been accepted, some features are enabled and some not. For an overview of initial configuration tasks for Eclipse GlassFish services and resources, see Initial Configuration Tasks.
In addition, you might want to reset default passwords, change names or locations of files, and so on. The following tables list the default administration values.
For the zip bundle of Eclipse GlassFish 7, the default administrator
login is |
Table 1-1 Default Administration Values
Item | Default |
---|---|
Domain Name |
|
Master Password |
|
Administration User |
|
Administration Server Port |
4848 |
HTTP Port |
8080 |
HTTPS Port |
8181 |
Pure JMX Clients Port |
8686 |
Message Queue Port |
7676 |
IIOP Port |
3700 |
IIOP/SSL Port |
3820 |
IIOP/SSL Port With Mutual Authentication |
3920 |
Table 1-2 Default Locations
Item | Default |
---|---|
Command-line Utility ( |
as-install |
Configuration Files |
domain-dir |
Log Files |
domain-dir |
Upgrade Tool ( |
as-install |
For information about replaceable items and default paths and files, see Default Paths and File Names.
Configuration Tasks
Some configuration tasks must be performed directly after installation for your Eclipse GlassFish environment to work as intended. For example, if you are using a database with Eclipse GlassFish, you need to set up database connectivity right away.
Some configuration situations are ongoing and will require you to make
changes many times during the life of your installation. You can use
either the Administration Console or the asadmin
utility to modify the
configuration. Changes are automatically applied to the appropriate
configuration file.
The following topics are addressed here:
Initial Configuration Tasks
This section maps the common configuration tasks to the command-line procedures in this guide. In some situations, the resource or service is automatically enabled and your configuration tasks involve adjusting or changing the default settings to suit your specific needs.
The following resources and services frequently require configuration immediately after installation:
- System Properties
- Domains
-
The initial
domain1
is created during installation. Additional configuration tasks might include such tasks as configuring additional domains or setting up automatic restart. See Administering Domains. - JVM
-
The initial tasks for configuring the JVM include creating JVM options and profilers. See Administering the Virtual Machine for the Java Platform.
- Logging
-
By default, logging is enabled, so basic logging works without additional configuration. However, you might want to change log levels, property values, or the location of log files. See Administering the Logging Service.
- Monitoring
-
By default, the monitoring service is enabled. However, monitoring for the individual modules is not enabled, so your first monitoring task is to enable monitoring for the modules that you want to monitor. See Administering the Monitoring Service.
- Life Cycle Modules
- Security
-
-
System Security. Initial configuration tasks might include setting up passwords, audit modules, and certificates. See "Administering System Security" in Eclipse GlassFish Security Guide.
-
User Security. Initial configuration tasks might include creating authentication realms and file users. See "Administering User Security" in Eclipse GlassFish Security Guide.
-
Message Security. Initial configuration tasks might include configuring a Java Cryptography Extension (JCE) provider, enabling default and non-default security providers, and configuring message protection policies. See "Administering Message Security" in Eclipse GlassFish Security Guide.
-
- Database Connectivity
-
The initial tasks involved in configuring Eclipse GlassFish to connect to the Apache Derby database include creating a Java Database Connectivity (JDBC) connection pool, creating a JDBC resource, and integrating a JDBC driver. See Administering Database Connectivity.
- EIS Connectivity
-
The initial tasks involved in configuring Eclipse GlassFish to connect to an enterprise information system (EIS) include creating a connector connection pool, creating a connector resource, editing a resource adapter configuration, creating a connector security map, creating a connector work security map, and creating an administered object (if needed). See Administering EIS Connectivity.
- Internet Connectivity
-
The initial tasks involved in making deployed web applications accessible by internet clients include creating HTTP network listeners and virtual servers, and configuring the HTTP listeners for SSL (if needed). See Administering Internet Connectivity.
- Object Request Broker (ORB)
-
An initial configuration task might involve creating an IIOP listener. See Administering the Object Request Broker (ORB).
- Jakarta Mail Service
-
An initial configuration task might involve creating a Jakarta Mail resource. See Administering the Jakarta Mail Service.
- Java Message Service (JMS)
-
Initial configuration tasks might include creating a physical destination, creating connection factories or destination resources, creating a JMS host (if the default JMS host is not adequate), adjusting connection pool settings (if needed), and configuring resource adapters for JMS. See Administering the Java Message Service (JMS).
- JNDI Service
-
An initial configuration task might involve creating a JNDI resource. See Administering the Java Naming and Directory Interface (JNDI) Service.
Information and instructions for accomplishing the tasks by using the Administration Console are contained in the Administration Console online help.
How Dotted Names Work for Configuration
After the initial configuration is working, you will continue to manage
ongoing configuration for the life of your Eclipse GlassFish
installation. You might need to adjust resources to improve
productivity, or issues might arise that require settings to be modified
or defaults to be reset. In some situations, an asadmin
subcommand is
provided for updating, such as the update-connector-work-security-map
subcommand. However, most updating is done by using the list
, get
,
and set
subcommands with dotted names. For detailed information about
dotted names, see the dotted-names
(5ASC) help page.
Dotted names also apply to monitoring, but the method is different. For information on using dotted names for monitoring, see How the Monitoring Tree Structure Works. |
The general process for working with configuration changes on the command line is as follows:
-
List the modules for the component of interest.
The following single mode example uses the | (pipe) character and the
grep
command to narrow the search:asadmin list "*" | grep http | grep listener
Information similar to the following is returned:
configs.config.server-config.network-config.network-listeners.network-listener.http-listener-1 configs.config.server-config.network-config.network-listeners.network-listener.http-listener-2 configs.config.server-config.network-config.protocols.protocol.admin-listener.http configs.config.server-config.network-config.protocols.protocol.admin-listener.http.file-cache configs.config.server-config.network-config.protocols.protocol.http-listener-1 configs.config.server-config.network-config.protocols.protocol.http-listener-1.http configs.config.server-config.network-config.protocols.protocol.http-listener-1.http.file-cache configs.config.server-config.network-config.protocols.protocol.http-listener-2 configs.config.server-config.network-config.protocols.protocol.http-listener-2.http configs.config.server-config.network-config.protocols.protocol.http-listener-2.http.file-cache configs.config.server-config.network-config.protocols.protocol.http-listener-2.ssl
-
Get the attributes that apply to the module you are interested in.
The following multimode example gets the attributes and values for
http-listener-1
:asadmin> get server-config.network-config.network-listeners.network-listener.http-listener-1.*
Information similar to the following is returned:
server.http-service.http-listener.http-listener-1.acceptor-threads = 1 server.http-service.http-listener.http-listener-1.address = 0.0.0.0 server.http-service.http-listener.http-listener-1.blocking-enabled = false server.http-service.http-listener.http-listener-1.default-virtual-server = server server.http-service.http-listener.http-listener-1.enabled = true server.http-service.http-listener.http-listener-1.external-port = server.http-service.http-listener.http-listener-1.family = inet server.http-service.http-listener.http-listener-1.id = http-listener-1 server.http-service.http-listener.http-listener-1.port = 8080 server.http-service.http-listener.http-listener-1.redirect-port = server.http-service.http-listener.http-listener-1.security-enabled = false server.http-service.http-listener.http-listener-1.server-name = server.http-service.http-listener.http-listener-1.xpowered-by = true
-
Modify an attribute by using the
set
subcommand.This example sets the
security-enabled
attribute ofhttp-listener-1
to true:asadmin> set server.http-service.http-listener.http-listener-1.security-enabled = true
Configuration Files
The bulk of the configuration information about Eclipse GlassFish
resources, applications, and instances is stored in the domain.xml
configuration file.
This file is the central repository for a given
administrative domain and contains an XML representation of the Eclipse GlassFish domain model.
The default location for the domain.xml
file is domain-dir/config
.
Eclipse GlassFish maintains a backup of the |
The logging.properties
file is used to configure the Java Util Logging system.
The default logging.properties
file is located in the same directory as the domain.xml
file.
For further information on the logging.properties
file,
see Logging Properties.
The asenv.conf
file is located in the as-install/config
directory.
Its purpose is to store the Eclipse GlassFish environment variables, such
as the installation location of the database, Message Queue, and so on.
Changes are automatically applied to the appropriate configuration file. Do not edit the configuration files directly. Manual editing is prone to error and can have unexpected results. |
Impact of Configuration Changes
Some configuration changes require that you restart the DAS or Eclipse GlassFish instances for the changes to take effect. Other changes are applied dynamically without requiring that the DAS or instances be restarted. The procedures in this guide indicate when a restart is required. Eclipse GlassFish enables you to determine whether the DAS or an instance must be restarted to apply configuration changes.
Some changes to resources or connection pools affect the applications that use the resources or connection pools. These changes do not require restart. However, any applications that use the resources or connection pools must be disabled and re-enabled or redeployed for the change to take effect.
The following topics are addressed here:
To Determine Whether the DAS or an Instance Requires Restart
-
Ensure that the DAS is running. To obtain information about the DAS or an instance, a running server is required.
-
Do one of the following:
-
To determine if the DAS requires restart, list the domains in your Eclipse GlassFish installation. Use the
list-domains
subcommand for this purpose.asadmin> list-domains [--domaindir domain-root-dir]
The domain-root-dir is the directory that contains the directories in which individual domains' configuration is stored. The default is as-install
/domains
, where as-install is the base installation directory of the Eclipse GlassFish software. If the DAS requires restart, a statement that restart is required is displayed. -
To determine if an instance requires restart, list information about the instance. Use the
list-instances
subcommand for this purpose.asadmin> list-instances instance-name
The instance-name is the name of the instance for which you are listing information. If the instance requires restart, one of the following pieces of information is displayed: a statement that restart is required, or a list of configuration changes that are not yet applied to the instance.
-
Example 1-1 Determining if the DAS Requires Restart
This example determines that the DAS for the domain domain1
requires
restart to apply configuration changes.
asadmin> list-domains
domain1 running, restart required to apply configuration changes
Command list-domains executed successfully.
Example 1-2 Determining if an Instance Requires Restart
This example determines that the instance pmd-i1
requires restart to
apply configuration changes.
asadmin> list-instances pmd-i1
pmd-i1 running; requires restart
Command list-instances executed successfully.
See Also
You can also view the full syntax and options of the subcommands by typing the following commands at the command line.
-
asadmin help list-domains
-
asadmin help list-instances
Configuration Changes That Require Restart
The following configuration changes require restart for the changes to take effect:
-
Changing JVM options
-
Changing port numbers
Changes to some port numbers, for example HTTP listener ports, do not require restart.
-
Changing log handler elements
-
Configuring certificates
-
Managing HTTP, JMS, IIOP, JNDI services
-
Enabling or disabling secure administration as explained in "Running Secure Admin" in Eclipse GlassFish Security Guide
Dynamic Configuration Changes
With dynamic configuration, changes take effect while the DAS or instance is running. The following configuration changes do not require restart:
-
Adding or deleting add-on components
-
Adding or removing JDBC, JMS, and connector resources and pools (Exception: Some connection pool properties affect applications.)
-
Changing a system property that is not referenced by a JVM option or a port
-
Adding file realm users
-
Changing logging levels
-
Enabling and disabling monitoring
-
Changing monitoring levels for modules
-
Enabling and disabling resources and applications
-
Deploying, undeploying, and redeploying applications
Changes That Affect Applications
Some changes to resources or connection pools affect the applications that use the resources or connection pools. These changes do not require restart. However, any applications that use the resources or connection pools must be disabled and re-enabled or redeployed for the change to take effect.
If you do not know which applications use the changed resources or connection pools, you can apply these changes by restarting the clusters orEclipse GlassFish instances to which applications are deployed. However, to minimize the disruption to the services that your applications provide, avoid restarting clusters or instances to apply these changes if possible. |
The following changes affect applications:
-
Creating or deleting resources (Exception: Changes to some JDBC, JMS, or connector resources do not affect applications.)
-
Modifying the following JDBC connection pool properties:
-
datasource-classname
-
associate-with-thread
-
lazy-connection-association
-
lazy-connection-enlistment
-
JDBC driver vendor-specific properties
-
-
Modifying the following connector connection pool properties:
-
resource-adapter-name
-
connection-definition-name
-
transaction-support
-
associate-with-thread
-
lazy-connection-association
-
lazy-connection-enlistment
-
Vendor-specific properties
-
Administration Tools
For the most part, you can perform the same tasks by using either the
graphical Administration Console or the asadmin
command-line utility,
however, there are exceptions.
The following Eclipse GlassFish administration tools are described here:
Administration Console
The Administration Console is a browser-based utility that features an easy-to-navigate graphical interface that includes extensive online help for the administrative tasks.
To use the Administration Console, the domain administration server
(DAS) must be running. Each domain has its own DAS, which has a unique
port number. When Eclipse GlassFish was installed, you chose a port
number for the DAS, or used the default port of 4848. You also specified
a user name and password if you did not accept the default login
(admin
with no password).
When specifying the URL for the Administration Console, use the port
number for the domain to be administered. The format for starting the
Administration Console in a web browser is http://`hostname
:`port. For
example:
http://kindness.example.com:4848
If the Administration Console is running on the host where Eclipse GlassFish was installed, specify localhost
for the host name. For
example:
http://localhost:4848
If the Administration Console is run on a host different from the host
where Eclipse GlassFish was installed, a secure connection (https
instead of http
) is used. Some browsers do not display pages on secure
connections by default and must be configured to permit secure protocols
(SSL and TLS).
If you try to use the Administration Console from a system through a
proxy server on another system back to the original system, while using
the system’s full host name (instead of To avoid this situation, do one of the following:
To enable secure admin, see "Managing Administrative Security" in Eclipse GlassFish Security Guide. |
You can change the Administration Console startup behavior using the startup options.
Available startup options are:
default
-
The Administration Console loads on demand when its first accessed. This is the default option.
always
-
The Administration Console loads during Eclipse Glassfish server startup.
never
-
Prevents the Administration Console from loading thereby prohibiting it.
To Enable the Administration Console On Demand Loading
This is a default option.
Enabling on demand loading of the Administration Console involves changing the value of the
property server.admin-service.property.adminConsoleStartup
. This property controls the
Administration Console loading.
-
Ensure that the DAS is running.
-
Change the value of the
server.admin-service.property.adminConsoleStartup
property todefault
. You can change this value either by setting a configuration property or by editing a file.-
To change this value by setting a configuration property, set the configuration property
server.admin-service.property.adminConsoleStartup
to the valuedefault
.asadmin> set server.admin-service.property.adminConsoleStartup=default
-
-
Restart the DAS. For instructions, see To Restart a Domain.
To Enable the Administration Console Loading At Server Startup
Enabling the Administration Console loading at Eclipse Glassfish server startup involves changing
the value of the property server.admin-service.property.adminConsoleStartup
. This property
controls the Administration Console loading.
-
Ensure that the DAS is running.
-
Change the value of the
server.admin-service.property.adminConsoleStartup
property toalways
. You can change this value either by setting a configuration property or by editing a file.-
To change this value by setting a configuration property, set the configuration property
server.admin-service.property.adminConsoleStartup
to a valuealways
.asadmin> set server.admin-service.property.adminConsoleStartup=always
-
-
Restart the DAS. For instructions, see To Restart a Domain.
To Disable the Administration Console Loading
Disabling the Administration Console loading involves changing the value of the property
server.admin-service.property.adminConsoleStartup
. This property controls the Administration
Console loading.
-
Ensure that the DAS is running.
-
Change the value of the
server.admin-service.property.adminConsoleStartup
property tonever
. You can change this value either by setting a configuration property or by editing the file.-
To change this value by setting a configuration property, set the configuration property
server.admin-service.property.adminConsoleStartup
to a valuenever
.asadmin> set server.admin-service.property.adminConsoleStartup=never
-
-
Restart the DAS. For instructions, see To Restart a Domain.
Help pages in the Administration Console
You can display the help material for a page in the Administration Console by clicking the Help button on the page. The initial help page describes the functions and fields of the page itself. Associated task instructions can be accessed on additional pages by clicking a link in the See Also list.
asadmin
Utility
The asadmin
utility is a command-line tool that runs subcommands for
identifying the operation or task that you want to perform. You can run
asadmin
subcommands either from a command prompt or from a script.
Running asadmin
subcommands from a script is helpful for automating
repetitive tasks. Basic information about how the asadmin
utility
works can be found in the asadmin
(1M) help page. For
instructions on using the asadmin
utility, see
Using the asadmin
Utility.
To issue an asadmin
subcommand in the standard command shell (single
mode), go to the as-install/bin
directory and type the asadmin
command followed by a subcommand. For example:
asadmin list-jdbc-resources
You can invoke multiple command mode (multimode) by typing asadmin
at
the command prompt, after which the asadmin>
prompt is presented. The
asadmin
utility continues to accept subcommands until you exit
multimode and return to the standard command shell. For example:
asadmin> list-jdbc-resources
You can display a help page for any asadmin
subcommand by typing
help
before the subcommand name. For example:
asadmin> help restart-domain
or
asadmin help restart-domain
A collection of the asadmin
help pages is available in HTML and PDF
format in the Eclipse GlassFish Reference
Manual.
REST Interfaces
Eclipse GlassFish provides representational state transfer (REST) interfaces to enable you to access monitoring and configuration data for Eclipse GlassFish, including data that is provided by newly installed add-on components. For more information, see Using REST Interfaces to Administer Eclipse GlassFish.
OSGi Module Management Subsystem
The OSGi module management subsystem that is provided with Eclipse GlassFish is the Apache Felix OSGi framework . To administer this framework, use the either of the following tools:
-
Apache Felix Gogo remote shell. This shell is provided with Eclipse GlassFish. The shell uses the Felix Gogo shell service to interact with the OSGi module management subsystem.
-
GlassFish OSGi Administration Console. This console is distributed as an add-on component for Eclipse GlassFish or as a set of files from the Maven GlassFish repository. In both distributions, the GlassFish OSGi Web Console is provided as an extension to the Administration Console and as a standalone web application. The GlassFish OSGi Administration Console is a customized version of the Apache Felix Web Console.
These tools enable you to perform administrative tasks on OSGi bundles such as:
-
Browsing installed OSGi bundles
-
Viewing the headers of installed OSGi bundles
-
Installing OSGi bundles
-
Controlling the life cycle of installed bundles
To Enable the Apache Felix Gogo Remote Shell
By default, the Apache Felix Gogo remote shell in Eclipse GlassFish is disabled. Before using the shell to administer OSGi bundles in Eclipse GlassFish, you must enable the shell.
Enabling the Apache Felix Gogo remote shell in Eclipse GlassFish involves
changing the value of the property glassfish.osgi.start.level.final
.
This property controls whether the OSGi start level service enables the
shell when the DAS or a Eclipse GlassFish instance is started.
-
Ensure that the DAS is running.
-
Change the value of the
glassfish.osgi.start.level.final
property from 2 to 3. If the domain includes clustered or standalone instances on remote hosts, perform this step on each remote host. You can change this value either by creating a Java system property or by editing a file.-
To change this value by creating a Java system property, create the Java system property
glassfish.osgi.start.level.final
with a value of 3.asadmin> create-jvm-options --target target -Dglassfish.osgi.start.level.final=3
- target
-
The target for which you are creating the property.
For the DAS, the target is `server`.
For a clustered or standalone instance, the target is the name of the instance. * To change this value by editing a file, edit the plain-text file as-install``/config/osgi.properties`` to change the value of the `glassfish.osgi.start.level.final` property from 2 to 3.
-
-
Restart the DAS. For instructions, see To Restart a Domain.
To Run Apache Felix Gogo Remote Shell Commands
The Apache Felix Gogo remote shell is integrated with the Eclipse GlassFish asadmin
command line utility. You can use the asadmin
subcommands osgi
and osgi-shell
to access the remote shell and run
OSGi shell commands.
To Run Remote Shell Commands Using the osgi
Subcommand
The osgi
subcommand delegates the command line to the Apache Felix
Gogo remote shell for the execution of OSGi shell commands. Commands are
executed by the remote shell and results are returned by the asadmin
utility. The osgi
subcommand is supported in remote mode only.
-
Ensure that the server is running. Remote commands require a running server.
-
Access the remote shell by using the
osgi
subcommand. For the full syntax and options for this subcommand, seeosgi
(1).
To Run Remote Shell Commands Using the osgi-shell
Subcommand
The osgi-shell
subcommand provides interactive access to the Apache
Felix Gogo remote shell for the execution of OSGi shell commands. OSGi
shell commands are executed on the server and results are printed on the client.
You can run multiple commands from a file or run commands interactively.
The osgi-shell
subcommand is supported in local mode only.
Unlike other local subcommands, however, the DAS and the server
instance whose shell is being accessed must be running.
-
Ensure that the server is running.
-
Access the remote shell by using the
osgi-shell
subcommand. For the full syntax and options for this subcommand, seeosgi-shell
(1).
Example 1-3 Listing Apache Felix Gogo Remote Shell Commands
This example lists Apache Felix Gogo remote shell commands. Some lines of output are omitted from this example for readability.
asadmin> osgi help
felix:bundlelevel
felix:cd
felix:frameworklevel
gogo:cat
gogo:each
gogo:echo
...
asadmin> osgi-shell
Use "exit" to exit and "help" for online help.
gogo$ help
felix:bundlelevel
felix:cd
felix:frameworklevel
gogo:cat
gogo:each
gogo:echo
Example 1-4 Running a Remote Shell Command
This example runs the Felix Remote Shell Command lb
without any
arguments to list all installed OSGi bundles. Some lines of output are
omitted from this example for readability.
asadmin> osgi lb
START LEVEL 2
ID|State |Level|Name
0|Active | 0|System Bundle
1|Active | 1|Metro Web Services API OSGi Bundle
2|Active | 1|jakarta.annotation API
Command osgi executed successfully.
...
asadmin> osgi-shell
Use "exit" to exit and "help" for online help.
gogo$ lb
START LEVEL 2
ID|State |Level|Name
0|Active | 0|System Bundle
1|Active | 1|Metro Web Services API OSGi Bundle
2|Active | 1|jakarta.annotation API
gogo$
Example 1-5 Determining the Services That an OSGi Bundle Provides
This example runs the Felix Remote Shell Command inspect
with the
service
option and the capability
option to determine the services
that OSGi bundle 251 provides. Some lines of output are omitted from
this example for readability.
asadmin> osgi inspect service capability 251
== GlassFish EJB Container for OSGi Enabled EJB Applications (251) provides services:
objectClass = org.glassfish.osgijavaeebase.Extender
service.id = 68
-----
objectClass = org.glassfish.osgijavaeebase.OSGiDeployer
service.id = 69
service.ranking = -2147483648
Command osgi executed successfully.
...
asadmin> osgi -shell
Use "exit" to exit and "help" for online help.
gogo$ inspect service capability 251
== GlassFish EJB Container for OSGi Enabled EJB Applications (251) provides services:
objectClass = org.glassfish.osgijavaeebase.Extender
service.id = 68
...
gogo$
To Download and Install the GlassFish OSGi Web Console
The GlassFish OSGi Web Console is distributed as follows:
-
As an add-on component for Eclipse GlassFish
-
As a set of files from the GlassFish Maven repository
In both distributions, the GlassFish OSGi Web Console is provided as an extension to the Administration Console and as a standalone web application.
-
Perform one of the following sets of steps, depending on how you are obtaining the GlassFish OSGi Web Console.
-
If you are obtaining the console as an add-on component, install the GlassFish OSGi Admin Console component.
-
If you are obtaining the console from the Maven repository, download and unzip the required files.
-
-
Download the following files to the parent of the
glassfish7
directory of your Eclipse GlassFish installation.glassfish-osgi-http-3.1.2.zip
-
Unzip the files that you downloaded.
The contents of the files are added to the as-install
/modules/autostart
directory of your Eclipse GlassFish installation. -
Restart the DAS. For instructions, see To Restart a Domain.
Next Steps
After downloading and installing the GlassFish OSGi Web Console, you can access the console as explained in the following sections:
To Access the GlassFish OSGi Web Console Through the Eclipse GlassFish Administration Console
A tab for the GlassFish OSGi Web Console is provided for the DAS and for every Eclipse GlassFish instance in a domain.
-
Ensure that the DAS and the instance for which you want to access the GlassFish OSGi Web Console are running.
-
Start the Eclipse GlassFish Administration Console. For instructions, see Administration Console.
-
Open the Administration Console page for the DAS or instance for which you are accessing the GlassFish OSGi Web Console.
-
For the DAS, in the navigation tree, select the server (Admin Server) node.
-
For a standalone instance, perform these steps:
-
In the navigation tree, expand the Standalone Instances node.
-
Under the Standalone Instances node, select the instance.
-
-
For a clustered instance, perform these steps:
-
In the navigation tree, expand the Clusters node.
-
Under the Clusters node, select the cluster that contains the instance. The General Information page for the cluster opens.
-
In the General Information page for the cluster, click the Instances tab. The Clustered Server Instances page for the cluster opens.
-
In the Server Instances table on the Clustered Server Instances page, select the instance.
-
-
-
On the Administration Console page for the DAS or instance, click the OSGi Console tab. You are prompted for the user name and password of the administrative user of the GlassFish OSGi Web Console.
-
In response to the prompt, provide the user name and password of the administrative user of the GlassFish OSGi Web Console. The user name and password of this user are both preset to
admin
. The GlassFish OSGi Web Console page opens.
To Access the GlassFish OSGi Web Console as a Standalone Web Application
-
Ensure that the DAS or the instance for which you want to access the GlassFish OSGi Web Console is running.
-
In a web browser, open the following location:
http://host:http-port/osgi/system/console/
- host
-
The host where the DAS or instance is running.
- http-port
-
The port on which Eclipse GlassFish listens for HTTP requests. The default is 8080.
For example, if the DAS is running on the local host and Eclipse GlassFish listens for HTTP requests on the default port, open the following location:
+
http://localhost:8080/osgi/system/console/
-
When prompted, provide the user name and password of the administrative user of the GlassFish OSGi Web Console.
The user name and password of this user are both preset to
admin
.
keytool
Utility
The keytool
utility is used to set up and work with Java Security
Socket Extension (JSSE) digital certificates. See
"Administering JSSE Certificates"
in Eclipse GlassFish Security Guide for instructions on using keytool
.
Java Monitoring and Management Console (JConsole)
Java SE provides tools to connect to an MBean server and view the MBeans that are registered with the server. JConsole is one such popular JMX Connector Client and is available as part of the standard Java SE distribution. For instructions on implementing JConsole in the Eclipse GlassFish environment, see Configuring JConsole to View Eclipse GlassFish Monitoring Data.
Instructions for Administering Eclipse GlassFish
Information and instructions on performing most of the administration
tasks from the command line are provided in this document and in the
asadmin
utility help pages. For instructions on accessing asadmin
online help, see To Display Help
Information for the asadmin
Utility or a Subcommand.
Information and instructions for accomplishing the tasks by using the Administration Console are contained in the Administration Console online help.
Instructions written for the Eclipse GlassFish tools use standard UNIX forward slashes (/) for directory path separators in commands and file names. If you are running Eclipse GlassFish on a Microsoft Windows system, use backslashes (\) instead. For example:
|
The following additional documents address specific administration areas:
-
Verifying and deploying applications Eclipse GlassFish Application Deployment Guide
2 General Administration
This chapter provides instructions for performing general administration
tasks in the Eclipse GlassFish 7 environment by
using the asadmin
command-line utility.
The following topics are addressed here:
Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.
Using the asadmin
Utility
Use the asadmin
utility to perform administrative tasks for Eclipse GlassFish from the command line or from a script. You can use this utility
instead of the Administration Console interface.
The following topics are addressed here:
Path to the asadmin
Utility
The asadmin
utility is located in the as-install/bin
directory. To
run the asadmin
utility without specifying the path, ensure that this
directory is in your path.
asadmin
Utility Syntax
The syntax for running the asadmin
utility is as follows:
asadmin [asadmin-util-options] [subcommand [subcommand-options] [operands]]
The replaceable items in this syntax are described in the subsections
that follow. For full details of this syntax, see the
asadmin
(1M)
help page.
Subcommands of the asadmin
Utility
The subcommand identifies the operation or task that you are performing. Subcommands are case-sensitive. Each subcommand is either a local subcommand or a remote subcommand.
-
A local subcommand can be run without a running domain administration server (DAS). However, to run the subcommand and have access to the installation directory and the domain directory, the user must be logged in to the machine that hosts the domain.
-
A remote subcommand is always run by connecting to a DAS and running the subcommand there. A running DAS is required.
For a list of the subcommands for this release of Eclipse GlassFish, see Section 1 of the Eclipse GlassFish 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 theasadmin
utility, not the subcommand. Theasadmin
utility options may precede or follow the subcommand, butasadmin
utility options after the subcommand are deprecated. Allasadmin
utility options must either precede or follow the subcommand. Ifasadmin
utility options are specified both before and after the subcommand, an error occurs. For a description of theasadmin
utility options, see theasadmin
(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 the Eclipse GlassFish Reference Manual.Not all subcommand options are supported for this release of Eclipse GlassFish. If you specify an unsupported option, a syntax error does not occur. Instead, the command runs successfully and the unsupported option is silently ignored.
A subcommand option may have the same name as an asadmin
utility
option, but the effects of the two options are different.
Options have a long form and a short form.
-
The short form of an option has a single dash (
-
) followed by a single character. -
The long form of an option has two dashes (
--
) followed by an option word.
For example, the short form and the long form of the option for specifying terse output are as follows:
-
Short form:
-t
-
Long form:
--terse
Most options require argument values, except Boolean options, which toggle to enable or disable a feature.
Operands of asadmin
Utility Subcommands
Operands specify the items on which the subcommand is to act. Operands
must follow the argument values of subcommand options, and are set off
by a space, a tab, or double dashes (--
). The asadmin
utility treats
anything that follows the subcommand options and their values as an
operand.
To Run an asadmin
Utility Subcommand in Single Mode
In single mode, you must type a separate asadmin
command for each
subcommand that you want to use. After the subcommand has run, you are
returned to the operating system’s command shell. Any asadmin
utility
options must be specified in each separate asadmin
command that you
run. If you require the same asadmin
utility options for multiple
subcommands, use the asadmin
utility in multimode. For more
information, see To Start a Multimode Session.
-
In the operating system’s command shell, run the
asadmin
utility, specifying the subcommand. -
If necessary, also specify any required
asadmin
utility options, subcommand options, and operands.
Example 2-1 Running an asadmin
Utility Subcommand in Single Mode
This example runs the list-applications
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
Eclipse GlassFish 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 the Eclipse GlassFish Reference Manual.
-
If you are displaying help information for a remote subcommand, ensure that the server is running.
Remote subcommands require a running server.
-
Specify the subcommand of interest as the operand of the
help
subcommand.If you run the
help
subcommand without an operand, help information for theasadmin
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
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. |
-
Do one of the following:
-
Run the
asadmin
utility without a subcommand. -
Use the
multimode
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 typeasadmin
subcommands at this prompt to administer Eclipse GlassFish.
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
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
Do not type Ctrl-C to end a multimode session. If a domain or Eclipse GlassFish instance is started from the multimode session, typing Ctrl-C kills the domain or instance process. |
You are returned to the operating system’s command shell and the
asadmin>
prompt is no longer displayed. If the asadmin>
prompt is
still displayed, you might have opened a multimode session within a
multimode session. In this situation, repeat this procedure to end the
remaining multimode session.
To Run a Set of asadmin
Subcommands From a File
Running a set of asadmin
subcommands from a file enables you to
automate repetitive tasks.
-
Create a plain text file that contains the sequence of subcommands that you want to run.
-
Run the
multimode
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 ofasadmin
subcommands -
The command to run the subcommands in the file
commands_file.txt
The commands_file.txt
file contains the asadmin
utility subcommands
to perform the following sequence of operations:
-
Creating the domain
customdomain
-
Starting the domain
customdomain
-
Listing all available subcommands
-
Stopping the domain
customdomain
-
Deleting the domain
customdomain
The content of the commands_file.txt
file is as follows:
create-domain --portbase 9000 customdomain
start-domain customdomain
list-commands
stop-domain customdomain
delete-domain customdomain
This example runs the sequence of subcommands in the commands_file.txt
file. Because the --portbase
option is specified for the
create-domain
subcommand in the file, the --port
asadmin
utility
option must also be set.
asadmin --port 9048 multimode --file commands_file.txt
See Also
For more information about the subcommands in the preceding example, see the following help pages:
To Run asadmin
Subcommands in --detach
Mode
You can use the --detach
option of the asadmin
utility to detach
asadmin
subcommands and run them in the background in detach mode. The
asadmin
--detach
option is useful for long-running subcommands and
enables you to run several independent subcommands from one console or
script.
-
Ensure that the server is running. Remote commands require a running server.
-
Detach and run the subcommand by using the
asadmin
--detach
option.
Example 2-10 Using the --detach
Option in Single Mode
This example uses the asadmin
--detach
option in single mode to run
the create-cluster
subcommand.
asadmin --detach create-cluster Cluster1
Job ID: 1
Command create-cluster started successfully.
Example 2-11 Using the --detach
Option in Multimode
This example uses the asadmin
--detach
option in multimode to run
the create-cluster
subcommand.
asadmin> create-cluster Cluster1 --detach
Job ID: 1
Command create-cluster started successfully.
Job IDs are assigned to subcommands that are started using the asadmin
--detach
option or that contain progress information. You can use the
list-jobs
subcommand to list jobs and their job IDs, the attach
subcommand to reattach to a job and view its status, and the
configure-managed-jobs
subcommand to configure how long information
about jobs is kept.
Example 2-12 Listing Jobs
This example runs the list-jobs
subcommand in multimode to list jobs
and job information.
asadmin> list-jobs
JOB ID COMMAND STATE EXIT CODE TIME OF COMPLETION
1 create-cluster COMPLETED SUCCESS 2013-02-15 16:16:16 PST
2 deploy COMPLETED FAILURE 2013-02-15 18:26:30 PST
Command list-jobs executed successfully
Example 2-13 Attaching to a Subcommand and Checking Its Status
This example runs the attach
subcommand in multimode to attach to the
create-cluster
subcommand with a job ID of 1
. If a subcommand is
still in progress, the output displays the current status, such as
percentage complete.
asadmin> attach 1
Command create-cluster executed with status SUCCESS.
Command attach executed successfully.
Example 2-14 Configuring Managed Jobs
This example runs the configure-managed-jobs
subcommand in multimode
to set the job retention period to 36 hours. Time periods can be
specified in Hh|Mm|Ss for hours, minutes, or seconds.
asadmin> configure-managed-jobs --job-retention-period=36h
Command configure-managed-jobs executed successfully.
See Also
For the full syntax and options of the subcommands in the preceding examples, see the following help pages:
Administering System Properties
Shared server instances will often need to override attributes defined in their referenced configuration. Any configuration attribute can be overridden through a system property of the corresponding name.
The following topics are addressed here:
To Create System Properties
Use the create-system-properties
subcommand in remote mode to create
or update one or more system properties of the domain or configuration.
Any configuration attribute can be overwritten through a system property
of the corresponding name.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create system properties by using the
create-system-properties
subcommand.Information about properties for the subcommand is included in this help page.
Example 2-15 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, cluster, or server instance or
configuration.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List system properties by using the
list-system-properties
subcommand.The existing system properties are displayed, including predefined properties such as
HTTP_LISTENER_PORT
andHTTP_SSL_LISTENER_PORT
.
Example 2-16 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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the existing system properties by using the
list-system-properties
subcommand. -
Delete the system property by using the
delete-system-property
subcommand. -
If necessary, notify users that the system property has been deleted.
Example 2-17 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.
Using Configuration Modularity
With configuration modularity in Eclipse GlassFish,
new modules can be added to Eclipse GlassFish distributions without
modifying the global domain.xml
configuration file. Default
configuration data for modules is stored in the modules themselves,
rather than in domain.xml
, and loaded when needed.
Module configuration elements are stored in domain.xml
only when the
default configuration included in the module is changed or when module
configuration elements are added to domain.xml
using the
create-module-config
subcommand. The delete-module-config
subcommand
removes module configuration elements from domain.xml
, and the
get-active-module-config
subcommand displays the current active
configuration of a module.
To Add the Default Configuration of a Module to domain.xml
Use the create-module-config
subcommand to add the default
configuration of a module to domain.xml
.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Add the default configuration of a module to
domain.xml
by using thecreate-module-config
subcommand.
Example 2-18 Adding Module Configuration to domain.xml
This example adds the default configuration of the web container module
to domain1
in server-config
(the default configuration). Use the
--dryrun
option to preview the configuration before it is added.
asadmin> create-module-config web-container
Command create-module-config executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-module-config
at the command line.
To Remove the Configuration of a Module From domain.xml
Use the delete-module-config
subcommand to remove the configuration of
a module from domain.xml
and cause the module to use the default
configuration included in the module.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Remove the configuration of a module from
domain.xml
by using thedelete-module-config
subcommand.
Example 2-19 Removing Module Configuration From domain.xml
This example deletes the configuration of the web container module from
domain1
in server-config
(the default configuration).
asadmin> delete-module-config web-container
Command delete-module-config executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-module-config
at the command line.
To Display the Current Active Configuration of a Module
Use the get-active-module-config
subcommand to display the current
active configuration of a module.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Display the current active configuration of a module by using the
get-active-module-config
subcommand.
Example 2-20 Displaying the Current Active Configuration of a Module
This example displays the current active configuration of the JMS
service in server-config
(the default configuration).
asadmin> get-active-module-config jms-service
At location: domain/configs/config[server-config]
<jms-service default-jms-host="default_JMS_host" type="EMBEDDED"
<jms-host port="7676" host="localhost" name="default_JMS_host"/>
</jms-service>
Command get-active-module-config executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help get-active-module-config
at the command line.
Administering Resources
This section contains instructions for integrating resources into the Eclipse GlassFish 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 Jakarta Mail
resources, custom resource, connector resource and work security map,
admin object, and resource adapter configuration.
The XML file must reside in the domain-dir/config
directory. If you
specify a relative path or simply provide the name of the XML file, this
subcommand will prepend domain-dir/config
to this operand.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Add resources from an XML file by using the
add-resources
subcommand.Information about properties for the subcommand is included in this help page.
-
Restart Eclipse GlassFish.
See To Restart a Domain.
Example 2-21 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 Eclipse GlassFish Version
Use the version
subcommand in remote mode to display information about
the Eclipse GlassFish version for a particular server. If the subcommand
cannot communicate with the server by using the specified login
(user/password) and target (host/port) information, then the local
version is displayed along with a warning message.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Display the version by using the
version
subcommand.
Example 2-22 Displaying Version Information
This example displays the version of Eclipse GlassFish on the local host.
asadmin> version
Version = Eclipse GlassFish 7.0.0 (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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List applications by using the
list-applications
subcommand.
Example 2-23 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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List containers by using the
list-containers
subcommand.
Example 2-24 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 : 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 Eclipse GlassFish module subsystem. The status
of each module is included. Possible statuses include NEW and READY.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List modules by using the
list-modules
subcommand.
Example 2-25 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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List subcommands by using the
list-commands
subcommand.
Example 2-26 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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List timers by using the
list-timers
subcommand.
Example 2-27 Listing Timers
This example lists the timers in a particular standalone server instance. There is one currently active timer set.
asadmin> list-timers server
1
The list-timers command was executed successfully.
To Show Component Status
Use the show-component-status
subcommand in remote mode to get the
status (either enabled or disabled) of the specified deployed component.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Show component status by using the
show-component-status
subcommand.
Example 2-28 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 Eclipse GlassFish
Eclipse GlassFish provides representational state transfer (REST) interfaces to enable you to access monitoring and configuration data for Eclipse GlassFish, including data that is provided by newly installed add-on components.
You can access the Eclipse GlassFish REST interfaces through client applications such as:
You can also use the Eclipse GlassFish REST interfaces in REST client applications that are developed in languages such as:
-
JavaScript
-
Ruby
-
Perl
-
Java
-
JavaFX
The implementation of the Eclipse GlassFish 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 . Information about Jakarta RESTful Web Services is here: https://jakarta.ee/specifications/restful-ws/
The following topics are addressed here:
Using REST URLs to Administer Eclipse GlassFish
Each object 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 Eclipse GlassFish monitoring and configuration data requires a running DAS.
REST URLs to Resources for Configuration and Monitoring Objects
The formats of the URLs to resources that represent objects 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 object. The path is the dotted name of the object in which each dot (
.
) is replaced with a slash (/
).The path to a Eclipse GlassFish instance is
servers/server/
instance-name, where instance-name is the name of the instance. For the DAS, instance-name isserver
and the path isservers/server/server
.
For more information, see the following documentation:
If the URL to a REST resource for Eclipse GlassFish 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 an object 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 an object 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.
-
A list of hypertext links to resources that represent
asadmin
subcommands for non-CRUD operations on the resource.
The following figure shows the web page for the REST resource for managing a domain.
REST URLs for Accessing the Log File
The server.log
file of the DAS is represented as a child that is named
view-log
of the resource for managing the domain. A child of the
resource for the server.log
file represents the log file details
The formats of the URLs to resources that represent the log file are as follows:
-
Log file:
http://
host:
port/management/domain/view-log
-
Log file details:
http://
host:
port/monitoring/domain/view-log/details
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.
You can use the optional start
parameter in the URL to the resource
for the log file to specify the number of characters at the start of the
file to skip. For example, to skip 10,000 characters, specify the URL as
http://localhost:4848/management/domain/view-log?start=10000
. This
example assumes that the DAS is running on the local host and uses the
default port for administration.
The resource for the log file returns the HTTP header
"X-Text-Append-Next"
, which contains the entire URL to pass to the
GET
method to return the changes since the last call. You can use this
header in client applications to get all log entries that were added in
particular interval. For example, by testing the value of the
"X-Text-Append-Next"
header in a client thread every 10 seconds, you
can monitor the log entries that were added in the last 10 seconds.
Using REST Resource Methods to Administer Eclipse GlassFish
The Eclipse GlassFish REST interfaces support methods for accessing objects in the monitoring and configuration object trees.
The following table shows the REST methods for administering monitoring and configuration data and the tasks that you can perform with each method. These methods are HTTP 1.1 primitives. For the detailed specification of these primitives, see Hypertext Transfer Protocol — HTTP/1.1 .
Table 2-1 REST Resource Methods for Administering Monitoring and Configuration Data
Task | REST Method |
---|---|
Determine the methods and method parameters that an object in the tree supports |
|
Retrieve data for an object in the tree |
|
Add an object to the tree |
|
Update an object in the tree |
|
Delete an object from the tree |
|
REST requests that add, update, or delete objects must specify the
The |
To Determine the Methods and Method Parameters That an Object in the Tree Supports
The methods and method parameters that an object in the tree supports depend on the REST resource that represents the object:
-
REST resources for monitoring support only the
GET
method. -
All REST resources for configuration support the
GET
method. However, only some REST resources for configuration also support thePOST
method and theDELETE
method.
Before performing any operations on an object in the tree, determine the methods and method parameters that the object supports.
You can specify the format in which this information is presented. For more information, see Formats for Resource Representation of Configuration Objects.
Each |
-
Ensure that the server is running.
Operations on REST resources for Eclipse GlassFish data require a running server.
-
Use the
GET
method on the REST resource that represents the object.The
GET
method returns 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-29 Determining the Methods and Method Parameters That an Object in the Tree Supports
This example uses the cURL utility to determine the methods and method
parameters that the resource for the node sj01
supports. The example
uses the following options of the cURL utility:
-
-X
to specify that theGET
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. The resource supports the GET
method and
the POST
method.
Line breaks and white space are added to enhance readability.
curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/nodes/node/sj01
{
"command":"Node",
"exit_code":"SUCCESS",
"extraProperties":{
"commands":[
{"path":"_delete-node","command":"delete-node","method":"DELETE"},
{"path":"_update-node","command":"_update-node","method":"POST"},
{"path":"ping-node-ssh","command":"ping-node-ssh","method":"GET"},
{"path":"update-node-ssh","command":"update-node-ssh","method":"POST"},
{"path":"update-node-config","command":"update-node-config","method":"POST"}],
"methods":[
{"name":"GET"},
{"name":"POST","messageParameters":{
"installDir":{"optional":"true","type":"string","key":"false"},
"nodeDir":{"optional":"true","type":"string","key":"false"},
"nodeHost":{"optional":"true","type":"string","key":"false"},
"type":{"optional":"true","type":"string","key":"false"}
}
}
],
"entity":{
"installDir":"\/export\/glassfish7",
"name":"sj01",
"nodeDir":null,
"nodeHost":
"sj01.example.com",
"type":"SSH"
},
"childResources":{
"application-ref":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/application-ref",
"resource-ref":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/resource-ref",
"ssh-connector":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/ssh-connector"
}
}
}
To Retrieve Data for an Object in the Tree
Retrieving data for an object in the tree obtains the following information about the REST resource that represents the object:
-
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 of Configuration Objects.
-
Ensure that the server is running.
Operations on REST resources for Eclipse GlassFish data require a running server.
-
Use the
GET
method on the REST resource that represents the object.
Example 2-30 Retrieving Data for an Object in the Tree
This example uses the cURL utility to retrieve data for the resource for
a the node sj01
. The example uses the following options of the cURL
utility:
-
-X
to specify that theGET
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 and white space are added to enhance readability.
curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/nodes/node/sj01
{
"command":"Node",
"exit_code":"SUCCESS",
"extraProperties":{
"commands":[
{"path":"_delete-node","command":"delete-node","method":"DELETE"},
{"path":"_update-node","command":"_update-node","method":"POST"},
{"path":"ping-node-ssh","command":"ping-node-ssh","method":"GET"},
{"path":"update-node-ssh","command":"update-node-ssh","method":"POST"},
{"path":"update-node-config","command":"update-node-config","method":"POST"}],
"methods":[
{"name":"GET"},
{"name":"POST","messageParameters":{
"installDir":{"optional":"true","type":"string","key":"false"},
"nodeDir":{"optional":"true","type":"string","key":"false"},
"nodeHost":{"optional":"true","type":"string","key":"false"},
"type":{"optional":"true","type":"string","key":"false"}
}
}
],
"entity":{
"installDir":"\/export\/glassfish7",
"name":"sj01",
"nodeDir":null,
"nodeHost":
"sj01.example.com",
"type":"SSH"
},
"childResources":{
"application-ref":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/application-ref",
"resource-ref":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/resource-ref",
"ssh-connector":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/ssh-connector"
}
}
}
To Add an Object to the Tree
-
Ensure that the server is running.
Operations on REST resources for Eclipse GlassFish data require a running server.
-
Determine the acceptable message parameters for the
POST
method of the resource that represents the parent of the object.For information about how to perform this step, see To Determine the Methods and Method Parameters That an Object in the Tree Supports.
-
Use the
POST
method on the REST resource that represents the parent of the object that you are adding. -
Confirm that the object has been added.
Perform this step on the resource that represents the object that you have just added, not the parent. For information about how to perform this step, see To Retrieve Data for an Object in the Tree.
Example 2-31 Adding an Object to the Tree
This example uses the cURL utility to add a JDBC resource object to the tree by creating a REST resource to represent the JDBC resource.
In this example, the DAS is running on the local host and the HTTP port for administration is 4848.
Line breaks are added to enhance readability.
-
This step determines the acceptable message parameters for the
POST
method of the resourcejdbc-resource
.curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/jdbc-resource { "command":"Jdbc-resource", "exit_code":"SUCCESS", "extraProperties":{ "commands":[], "methods":[ {"name":"GET"}, {"name":"POST","messageParameters":{ "description":{"acceptableValues":"","optional":"true","type":"string","defaultValue":""}, "enabled":{"acceptableValues":"",optional":"true","type":"boolean",defaultValue":"true"}, "id":{"acceptableValues":"","optional":"false","type":"string","defaultValue":""}, "poolName":{"acceptableValues":"","optional":"false","type":"string","defaultValue":""}, "property":{"acceptableValues":"","optional":"true","type":"string","defaultValue":"}, "target":{"acceptableValues":"","optional":"true","type":"string","defaultValue":""} } } ], "childResources":{ "jdbc\/__TimerPool": "https:\/\/localhost:4848\/management\/domain\/resources\/jdbc-resource\/jdbc%2F__TimerPool", "jdbc\/__default": "https:\/\/localhost:4848\/management\/domain\/resources\/jdbc-resource\/jdbc%2F__default" } } }
-
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 tojdbc/myjdbcresource
. -
connectionpoolid
is set toDerbyPool
.curl -X POST -H "X-Requested-By: GlassFish REST HTML interface" -d id=jdbc/myjdbcresource -d connectionpoolid=DerbyPool http://localhost:4848/management/domain/resources/jdbc-resource
-
-
This step confirms that the object has been added by retrieving data for the REST resource that represents the object.
curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource { "command":"Jdbc-resource", "exit_code":"SUCCESS", "extraProperties":{ "commands":[], "methods":[ {"name":"GET"}, {"name":"POST","messageParameters":{ "description":{"optional":"true","type":"string","key":"false"}, "enabled":{"optional":"true","type":"boolean","defaultValue":"true","key":"false"}, "jndiName":{"optional":"true","type":"string","key":"true"}, "objectType":{"optional":"true","type":"string","defaultValue":"user","key":"false"}, "poolName":{"optional":"true","type":"string","key":"false"} } }, {"name":"DELETE","messageParameters":{ "target":{"acceptableValues":"","optional":"true","type":"string","defaultValue":""} } } ], "childResources":{ "property": "https:\/\/localhost:4848\/management\/domain\/resources\/jdbc-resource\/jdbc%2Fmyjdbcresource\/property" } } }
To Update an Object in the Tree
-
Ensure that the server is running. Operations on REST resources for Eclipse GlassFish data require a running server.
-
Determine the acceptable message parameters for the
POST
method of the resource that represents the object. For information about how to perform this step, see To Determine the Methods and Method Parameters That an Object in the Tree Supports. -
Use the
POST
method on the REST resource that represents the object that you are updating. -
Confirm that the object has been updated. For information about how to perform this step, see To Retrieve Data for an Object in the Tree.
Example 2-32 Updating an Object in the Tree
This example uses the cURL utility to update a JDBC resource in the tree by modifying the REST resource that represents the JDBC resource.
In this example, the DAS is running on the local host and the HTTP port for administration is 4848.
Line breaks are added to enhance readability.
-
This step determines the acceptable message parameters for the
POST
method of the resourcejdbc-myjdbcresource
.curl -X OPTIONS -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc-myjdbcresource { "command":"Jdbc-resource", "exit_code":"SUCCESS", "extraProperties":{ "commands":[], "methods":[ {"name":"GET"}, {"name":"POST","messageParameters":{ "description":{"optional":"true","type":"string","key":"false"}, "enabled":{"optional":"true","type":"boolean","defaultValue":"true","key":"false"}, "jndiName":{"optional":"true","type":"string","key":"true"}, "objectType":{"optional":"true","type":"string","defaultValue":"user","key":"false"}, "poolName":{"optional":"true","type":"string","key":"false"} } }, {"name":"DELETE","messageParameters":{ "target":{"acceptableValues":"","optional":"true","type":"string","defaultValue":""} } } ], "childResources":{ "property": "https:\/\/localhost:4848\/management\/domain\/resources\/jdbc-resource\/jdbc%2Fmyjdbcresource\/property" } } }
-
This step updates the REST resource
jdbc-myjdbcresource
to disable the JDBC resource thatjdbc-myjdbcresource
represents. The-d
option of the cURL utility sets theenabled
message parameter todisabled
.curl -X POST -H "X-Requested-By: GlassFish REST HTML interface" -d "enabled=false" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource
-
This step confirms that the object has been updated by retrieving data for the REST resource that represents the object.
curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource { "command":"Jdbc-resource", "exit_code":"SUCCESS", "extraProperties":{ "commands":[], "methods":[ {"name":"GET"}, {"name":"POST","messageParameters":{ "description":{"optional":"true","type":"string","key":"false"}, "enabled":{"optional":"true","type":"boolean","defaultValue":"true","key":"false"}, "jndiName":{"optional":"true","type":"string","key":"true"}, "objectType":{"optional":"true","type":"string","defaultValue": "user","key":"false"}, "poolName":{"optional":"true","type":"string","key":"false"} } }, {"name":"DELETE","messageParameters":{ "target":{"acceptableValues":"","optional":"true","type":"string","defaultValue":""} } } ], "entity":{ "description":null, "enabled":"false", "jndiName":"jdbc\/myjdbcresource", "objectType": "user", "poolName":"DerbyPool" }, "childResources":{ "property": "https:\/\/localhost:4848\/management\/domain\/resources\/jdbc-resource\/ jdbc%2Fmyjdbcresource\/property" } } }
To Delete an Object From the Tree
-
Ensure that the server is running.
Operations on REST resources for Eclipse GlassFish data require a running server.
-
Confirm that the object can be deleted.
For information about how to perform this step, see To Determine the Methods and Method Parameters That an Object in the Tree Supports.
-
Confirm that the object has been deleted.
Perform this step on the resource that represents the parent of the object that you have just deleted. For information about how to perform this step, see To Retrieve Data for an Object in the Tree.
Example 2-33 Deleting an Object 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 and white space are added to enhance readability.
-
This step confirms that the object can be deleted by retrieving the REST methods that the resource
jdbc-myjdbcresource
supports.curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource { "command":"Jdbc-resource", "exit_code":"SUCCESS", "extraProperties":{ "commands":[], "methods":[ {"name":"GET"}, {"name":"POST","messageParameters":{ "description":{"optional":"true","type":"string","key":"false"}, "enabled":{"optional":"true","type":"boolean","defaultValue":"true","key":"false"}, "jndiName":{"optional":"true","type":"string","key":"true"}, "objectType":{"optional":"true","type":"string","defaultValue":"user","key":"false"}, "poolName":{"optional":"true","type":"string","key":"false"} } }, {"name":"DELETE","messageParameters":{ "target":{"acceptableValues":"","optional":"true","type":"string","defaultValue":""} } } ], "childResources":{ "property": "https:\/\/localhost:4848\/management\/domain\/resources\/jdbc-resource\/ jdbc%2Fmyjdbcresource\/property" } } }
-
This step deletes the
jdbc/myjdbcresource
resource.curl -X DELETE -H "X-Requested-By: GlassFish REST HTML interface" http://localhost:4848/management/domain/resources/ jdbc-resource/jdbc%2Fmyjdbcresource
-
This step confirms that the object has been deleted by retrieving data for the REST resource that represents the parent of the object.
curl -X GET -H "Accept: application/json" http://localhost:4848/management/domain/resources/jdbc-resource { "command":"Jdbc-resource", "exit_code":"SUCCESS", "extraProperties":{ "commands":[], "methods":[ {"name":"GET"}, {"name":"POST","messageParameters":{ "description":{"acceptableValues":"","optional":"true","type":"string","defaultValue":""}, "enabled":{"acceptableValues":"",optional":"true","type":"boolean",defaultValue":"true"}, "id":{"acceptableValues":"","optional":"false","type":"string","defaultValue":""}, "poolName":{"acceptableValues":"","optional":"false","type":"string","defaultValue":""}, "property":{"acceptableValues":"","optional":"true","type":"string","defaultValue":"}, "target":{"acceptableValues":"","optional":"true","type":"string","defaultValue":""} } } ], "childResources":{ "jdbc\/__TimerPool": "https:\/\/localhost:4848\/management\/domain\/resources\/jdbc-resource\/jdbc%2F__TimerPool", "jdbc\/__default": "https:\/\/localhost:4848\/management\/domain\/resources\/jdbc-resource\/jdbc%2F__default" } } }
Resources for asadmin
Subcommands That Perform Non-CRUD Operations
The Eclipse GlassFish 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 REST resources that represent the
asadmin
subcommands for performing these operations. Each resource is
a child of the resource on which the operation is performed. The child
resources do not represent objects in the configuration object tree.
For example, the resource that represents a node provides child
resources for the following asadmin
subcommands that perform non-CRUD
operations on the node:
-
ping-node-ssh
-
update-node-config
-
update-node-ssh
Securing Eclipse GlassFish REST Interfaces
The Eclipse GlassFish REST interfaces support the following authentication schemes for securing the REST interfaces:
-
Basic authentication over a secure connection
-
Authentication by using session tokens
When security is enabled, you must specify https
as the protocol in
the URLs to REST resources and provide a user name and password.
Setting Up Basic Authentication Over a Secure Connection
Setting up basic authentication over a secure connection to secure Eclipse GlassFish REST interfaces involves the following sequence of tasks:
-
Adding an
admin-realm
user to theasadmin
user group -
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" in Eclipse GlassFish Security Guide
-
"To Create a File User" in Eclipse GlassFish Security Guide
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
To Secure REST Interfaces by Using Session Tokens
Basic authentication requires a REST client to cache a user’s credentials to enable the client to pass the credentials with each request. If you require a REST client not to cache credentials, your client must use session tokens for authentication.
-
Request a session token by using the
POST
method on the resource athttp://`host
:`port`/management/sessions`. Eclipse GlassFish uses basic authentication to authenticate the client, generates a session token, and passes the token to the client. -
In each subsequent request that requires authentication, use the token to authenticate the client.
-
Create a cookie that is named
gfresttoken
the value of which is the token. -
Send the cookie with the request.
-
When the token is no longer required, retire the token by using the
DELETE
method on the resource athttp://`host
:`port`/management/sessions/{tokenvalue
}`.If a client does not explicitly retire a token, the token is retired after 30 minutes of inactivity.
-
Formats for Resource Representation of Configuration Objects
The Eclipse GlassFish REST interfaces represent resources for configuration objects in the following formats:
Eclipse GlassFish enables you to specify the resource representation through the filename extension in the URL or through the HTTP header:
-
To specify the resource representation through the filename extension in the URL, specify the appropriate extension as follows:
-
For JSON, specify the
.json
extension. -
For XML, specify the
.xml
extension. -
For HTML, omit the extension.
-
-
How to specify the resource representation through the HTTP header depends on the client that you are using to access the resource. 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 for Configuration Objects
The general format for the JSON representation of a resource for a configuration object is as follows:
{
"command":"resource",
"exit_code":"code",
"extraProperties":{
"commands":[command-list],
"methods":[method-list],
"entity":{attributes},
"childResources":{children}
}
}
The replaceable items in this format are as follows:
- resource
-
The name of the resource.
- code
-
The result of the attempt to get the resource.
- command-list
-
One or more metadata sets separated by a comma (
,
) that represent theasadmin
subcommands for performing non—CRUD operations on the resource. For the format of each metadata set, see JSON Representation of a Command in a Command List. - 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. - attributes
-
Zero or more name-value pairs separated by a comma (
,
). Each name-value pair is specified as `“name”:`value. - children
-
Zero or more child resources separated by a comma (
,
). Each child resource is specified as "resource-name":"url".- resource-name
-
The name of the resource as displayed in client applications that access the parent of the resource.
- url
-
The URL to the child resource.
JSON Representation of a Command in a Command List
The JSON representation of a command in a command list is as follows:
{
"path":"command-path",
"command":"command-name",
"method":"rest-method"
}
The replaceable items in this format are as follows:
- command-path
-
The relative path to REST resource that represents the command. This path is relative to the URL of the REST resource that is the parent of the resource that represents the command.
- command-name
-
The name of the command as displayed in client applications that access the resource.
- rest-method
-
The REST resource method that the command invokes when the command is run. The method is
GET
,POST
, orDELETE
.
JSON Representation of a Method in a Method List
The JSON representation of a method in a method list is as follows:
{
"name":"method-name",
"messageParameters":{
message-parameter-list
}
"queryParameters":{
queryparameter- list
}
}
The replaceable items in this format are as follows:
- method-name
-
The name of the method, which is
GET
,POST
, orDELETE
. - 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:
defaultValue
-
The default value of the parameter.
acceptableValues
-
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. Iffalse
, the parameter is required. key
-
Indicates whether the parameter is key. If
true
, the parameter is key. Iffalse
, the parameter is not key.
Example JSON Resource Representation for a Configuration Object
This example shows the JSON representation of the resource for the node
sj01
. 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/nodes/node/sj01
.
Line breaks and white space are added to enhance readability.
{
"command":"Node",
"exit_code":"SUCCESS",
"extraProperties":{
"commands":[
{"path":"_delete-node","command":"delete-node","method":"DELETE"},
{"path":"_update-node","command":"_update-node","method":"POST"},
{"path":"ping-node-ssh","command":"ping-node-ssh","method":"GET"},
{"path":"update-node-ssh","command":"update-node-ssh","method":"POST"},
{"path":"update-node-config","command":"update-node-config","method":"POST"}],
"methods":[
{"name":"GET"},
{"name":"POST","messageParameters":{
"installDir":{"optional":"true","type":"string","key":"false"},
"nodeDir":{"optional":"true","type":"string","key":"false"},
"nodeHost":{"optional":"true","type":"string","key":"false"},
"type":{"optional":"true","type":"string","key":"false"}
}
}
],
"entity":{
"installDir":"\/export\/glassfish7",
"name":"sj01",
"nodeDir":null,
"nodeHost":
"sj01.example.com",
"type":"SSH"
},
"childResources":{
"application-ref":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/application-ref",
"resource-ref":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/resource-ref",
"ssh-connector":
"https:\/\/localhost:4848\/management\/domain\/nodes\/node\/sj01\/ssh-connector"
}
}
}
XML Resource Representation for Configuration Objects
The general format for the XML representation of a resource for a configuration object is as follows:
<map>
<entry key="extraProperties">
<map>
<entry key="methods">
<list>
methods
</list>
</entry>
<entry key="entity">
<map>
attributes
</map>
</entry>
<entry key="commands">
<list>
commands
</list>
</entry>
<entry key="childResources">
<map>
children
</map>
</entry>
</map>
</entry>
<entry key="message"></entry>
<entry key="exit_code" value="code"></entry>
<entry key="command" value="resource"></entry>
</map>
The replaceable items in this format are as follows:
- methods
-
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.
- attributes
-
Zero or more XML elements that represent the attributes of the resource. Each element specifies a name-value pair as follows:
<entry key="name" value="value"></entry>
- commands
-
One or more XML elements that represent the
asadmin
subcommands for performing non—CRUD operations on the resource. For the format of each element, see XML Representation of a Command. - children
-
Zero or more XML elements that represent the children of the resource. Each element is specified as follows:
<entry key="resource-name" value="url"></entry>
- resource-name
-
The name of the resource as displayed in client applications that access the parent of the resource.
- url
-
The URL to the child resource.
- code
-
The result of the attempt to get the resource.
- resource
-
The name of the resource.
XML Representation of a Resource Method
The XML representation of a method in a method list is as follows:
<map>
<entry key="name" value="method-name"></entry>
<entry key="messageParameters">
message-parameter-list
</entry>
<entry key="queryParameters">
message-parameter-list
</entry>
</map>
The replaceable items in this format are as follows:
- method-name
-
The name of the method, which is
GET
,POST
, orDELETE
. - message-parameter-list
-
Zero or more XML elements 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 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 Command
The XML representation of a command is as follows:
<map>
<entry key="command" value="command-name"></entry>
<entry key="path" value="command-path"></entry>
<entry key="method" value="rest-method"></entry>
</map>
The replaceable items in this format are as follows:
- command-name
-
The name of the command as displayed in client applications that access the resource.
- command-path
-
The relative path to REST resource that represents the command. This path is relative to the URL of the REST resource that is the parent of the resource that represents the command.
- rest-method
-
The REST resource method that the command invokes when the command is run. The method is
GET
,POST
, orDELETE
.
XML Representation of a Message Parameter or a Query Parameter
The XML representation of a message parameter or a query parameter is as follows:
<map>
<entry key="parameter-name">
<map>
attributes
</map>
</entry>
</map>
The replaceable items in this format are as follows:
- parameter-name
-
The name of the parameter.
- attributes
-
One or more XML elements that represent the attributes for the parameter. Each element specifies a name-value pair as follows:
<entry key="name" value="value"></entry>
Possible attributes are as follows:
defaultValue
-
The default value of the parameter.
acceptablevalues
-
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. Iffalse
, the parameter is required. key
-
Indicates whether the parameter is key. If
true
, the parameter is key. Iffalse
, the parameter is not key.
Example XML Resource Representation
This example shows the XML representation of the resource for the node
sj01
. 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/nodes/node/sj01
.
Line breaks and white space are added to enhance readability.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<map>
<entry key="extraProperties">
<map>
<entry key="methods">
<list>
<map>
<entry key="name" value="GET"/>
</map>
<map>
<entry key="name" value="POST"/>
<entry key="messageParameters">
<map>
<entry key="installDir">
<map>
<entry key="optional" value="true"/>
<entry key="type" value="string"/>
<entry key="key" value="false"/>
</map>
</entry>
<entry key="nodeDir">
<map>
<entry key="optional" value="true"/>
<entry key="type" value="string"/>
<entry key="key" value="false"/>
</map>
</entry>
<entry key="type">
<map>
<entry key="optional" value="true"/>
<entry key="type" value="string"/>
<entry key="key" value="false"/>
</map>
</entry>
<entry key="nodeHost">
<map>
<entry key="optional" value="true"/>
<entry key="type" value="string"/>
<entry key="key" value="false"/>
</map>
</entry>
</map>
</entry>
</map>
</list>
</entry>
<entry key="entity">
<map>
<entry key="installDir" value="/export/glassfish7"/>
<entry key="name" value="sj01"/>
<entry key="nodeDir" value=""/>
<entry key="type" value="SSH"/>
<entry key="nodeHost" value="sj01example.com"/>
</map>
</entry>
<entry key="commands">
<list>
<map>
<entry key="command" value="delete-node"/>
<entry key="path" value="_delete-node"/>
<entry key="method" value="DELETE"/>
</map>
<map>
<entry key="command" value="_update-node"/>
<entry key="path" value="_update-node"/>
<entry key="method" value="POST"/>
</map>
<map>
<entry key="command" value="ping-node-ssh"/>
<entry key="path" value="ping-node-ssh"/>
<entry key="method" value="GET"/>
</map>
<map>
<entry key="command" value="update-node-ssh"/>
<entry key="path" value="update-node-ssh"/>
<entry key="method" value="POST"/>
</map>
<map>
<entry key="command" value="update-node-config"/>
<entry key="path" value="update-node-config"/>
<entry key="method" value="POST"/>
</map>
</list>
</entry>
<entry key="childResources">
<map>
<entry key="application-ref"
value="https://localhost:4848/management/domain/nodes/node/sj01/application-ref"/>
<entry key="ssh-connector"
value="https://localhost:4848/management/domain/nodes/node/sj01/ssh-connector"/>
<entry key="resource-ref"
value="https://localhost:4848/management/domain/nodes/node/sj01/resource-ref"/>
</map>
</entry>
</map>
</entry>
<entry key="message"/>
<entry key="exit_code" value="SUCCESS"/>
<entry key="command" value="Node"/>
</map>
HTML Resource Representation for Configuration Objects
The format for the HTML representation of a resource for a configuration object 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.
-
A list of hypertext links to resources that represent
asadmin
subcommands for non-CRUD operations on the resource.
For a sample web page, see Figure 2-1 Web Page for the REST 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/nodes/node/sj01
.
Formats for Resource Representation of Monitoring Objects
The Eclipse GlassFish REST interfaces represent resources for monitoring data in the following formats:
JSON Resource Representation for Monitoring Objects
The general format for the JSON representation of a resource for a monitoring object is as follows:
{
"message":"",
"command":"Monitoring Data",
"exit_code":"code",
"extraProperties":{
"entity":{
statistics-list
},
"childResources":{
children
}
}
}
The replaceable items in this format are as follows:
- code
-
The result of the attempt to get the resource.
- statistics-list
-
Zero or more metadata sets separated by a comma (
,
) that represent the statistics that the monitoring object provides. For the format of each metadata set, see JSON Representation of a Statistic in a Statistics List. - children
-
Zero or more child resources separated by a comma (
,
). Each child resource is specified as "resource-name":"url".- resource-name
-
The name of the resource as displayed in client applications that access the parent of the resource.
- url
-
The URL to the child resource.
JSON Representation of a Statistic in a Statistics List
The JSON representation of a counter statistic in a statistics list is as follows:
"statistic":{
"count":count,
"lastsampletime":last-sample-time,
"description":"description",
"unit":"unit",
"name":"name",
"starttime":start-time
}
The JSON representation of a range statistic in a statistics list is as follows:
"statistic":{
"highwatermark":highest-value,
"lowwatermark":lowest-value,
"current":current-value
"lastsampletime":last-sample-time,
"description":"description",
"unit":"unit",
"name":"name",
"starttime":start-time
}
The replaceable items in these formats are as follows:
- statistic
-
The name of the statistic.
- count
-
Counter statistics only: The current value of the statistic.
- highest-value
-
Range statistics only: The highest value of the statistic since monitoring of the statistic began.
- lowest-value
-
Range statistics only: The lowest value of the statistic since monitoring of the statistic began.
- current-value
-
Range statistics only: The lowest value of the statistic since monitoring of the statistic began.
- last-sample-time
-
The time in UNIX time at which the statistic was last sampled.
- description
-
A textual description of what the statistic represents.
- unit
-
The unit of measurement of the statistic, which is one of the following units of measurement:
count
-
The cumulative value of an attribute that increases with time.
range
-
The lowest value, highest value, and current value of an attribute that can increase or decrease with time.
boundedrange
-
The lowest value, highest value, and current value of an attribute that can increase or decrease with time and has fixed limits.
string
-
A string that represents an attribute value. A string statistic is similar to a count, except that the values are not ordered. Typically, a string statistic represents the state of an object, for example,
CONNECTED
,CLOSED
, orDISCONNECTED
. time
-
Values of an attribute that provide the following timing measurements for an operation:
-
The number of times the operation was performed.
-
The maximum amount of time to perform the operation once.
-
The minimum amount of time to perform the operation once.
-
The total amount of time that has been spent performing the operation.
-
The average amount of time to perform the operation.
-
- name
-
The name of the statistic as displayed in client applications that access the resource that contains the statistic.
- start-time
-
The time in UNIX time at which monitoring of the statistic began.
Example JSON Resource Representation for a Monitoring Object
This example shows the JSON representation of the monitoring object that
provides class loader statistics for the virtual machine for the Java
platform. 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/monitoring/domain/server/jvm/class-loading-system
.
Line breaks and white space are added to enhance readability.
{
"message":"",
"command":"Monitoring Data",
"exit_code":"SUCCESS",
"extraProperties":{
"entity":{
"loadedclass-count":{
"count":8521,
"lastsampletime":1300726961018,
"description":"Number of classes currently loaded in the Java virtual
machine",
"unit":"count",
"name":"LoadedClassCount",
"starttime":1300483924126
},
"totalloadedclass-count":{
"count":8682,
"lastsampletime":1300726961018,
"description":"Total number of classes that have been loaded since the
Java virtual machine has started execution",
"unit":"count",
"name":"TotalLoadedClassCount",
"starttime":1300483924127
},
"unloadedclass-count":{
"count":161,
"lastsampletime":1300726961018,
"description":"Total number of classes unloaded since the Java virtual
machine has started execution",
"unit":"count",
"name":"UnLoadedClassCount",
"starttime":1300483924127
}
},"childResources":{}
}
}
XML Resource Representation for Monitoring Objects
The general format for the XML representation of a resource for a monitoring object is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<map>
<entry key="extraProperties">
<map>
<entry key="entity">
<map>
statistics
</map>
</entry>
<entry key="childResources">
<map>
children
</map>
</entry>
</map>
</entry>
<entry key="message" value=""></entry>
<entry key="exit_code" value="code"></entry>
<entry key="command" value="Monitoring Data"></entry>
</map>
The replaceable items in this format are as follows:
- statistics
-
Zero or more XML elements that represent the statistics that the monitoring object provides. For the format of each element, see XML Representation of a Statistic.
- children
-
Zero or more XML elements that represent the children of the resource. Each element is specified as follows:
<entry key="resource-name" value="url"></entry>
- resource-name
-
The name of the resource as displayed in client applications that access the parent of the resource.
- url
-
The URL to the child resource.
- code
-
The result of the attempt to get the resource.
XML Representation of a Statistic
The XML representation of a counter statistic is as follows:
<entry key="statistic">
<map>
<entry key="unit" value="unit"></entry>
<entry key="starttime">
<number>start-time</number>
</entry>
<entry key="count">
<number>count</number>
</entry>
<entry key="description" value="description"></entry>
<entry key="name" value="name"></entry>
<entry key="lastsampletime">
<number>last-sample-time</number>
</entry>
</map>
</entry>
The XML representation of a range statistic is as follows:
<entry key="statistic">
<map>
<entry key="unit" value="unit"></entry>
<entry key="starttime">
<number>start-time</number>
</entry>
<entry key="highwatermark">
<number>highest-value</number>
</entry>
<entry key="lowwatermark">
<number>lowest-value</number>
</entry>
<entry key="current">
<number>current-value</number>
</entry>
<entry key="description" value="description"></entry>
<entry key="name" value="name"></entry>
<entry key="lastsampletime">
<number>last-sample-time</number>
</entry>
</map>
</entry>
The replaceable items in these formats are as follows:
- statistic
-
The name of the statistic.
- unit
-
The unit of measurement of the statistic, which is one of the following units of measurement:
count
-
The cumulative value of an attribute that increases with time.
range
-
The lowest value, highest value, and current value of an attribute that can increase or decrease with time.
boundedrange
-
The lowest value, highest value, and current value of an attribute that can increase or decrease with time and has fixed limits.
string
-
A string that represents an attribute value. A string statistic is similar to a count, except that the values are not ordered. Typically, a string statistic represents the state of an object, for example,
CONNECTED
,CLOSED
, orDISCONNECTED
. time
-
Values of an attribute that provide the following timing measurements for an operation:
-
The number of times the operation was performed.
-
The maximum amount of time to perform the operation once.
-
The minimum amount of time to perform the operation once.
-
The total amount of time that has been spent performing the operation.
-
The average amount of time to perform the operation.
-
- start-time
-
The in time in UNIX time at which monitoring of the statistic began.
- count
-
Counter statistics only: The current value of the statistic.
- highest-value
-
Range statistics only: The highest value of the statistic since monitoring of the statistic began.
- lowest-value
-
Range statistics only: The lowest value of the statistic since monitoring of the statistic began.
- current-value
-
Range statistics only: The lowest value of the statistic since monitoring of the statistic began.
- description
-
A textual description of what the statistic represents.
- name
-
The name of the statistic as displayed in client applications that access the resource that contains the statistic.
- last-sample-time
-
The time in UNIX time at which the statistic was last sampled.
Example XML Resource Representation for a Monitoring Object
This example shows the XML representation of the monitoring object that
provides class loader statistics for the virtual machine for the Java
platform. 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/monitoring/domain/server/jvm/class-loading-system
.
Line breaks and white space are added to enhance readability.
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<map>
<entry key="extraProperties">
<map>
<entry key="entity">
<map>
<entry key="unloadedclass-count">
<map>
<entry key="unit" value="count"/>
<entry key="starttime">
<number>1300483924127</number>
</entry><entry key="count">
<number>161</number>
</entry>
<entry key="description" value="Total number of classes unloaded since
the Java virtual machine has started execution"/>
<entry key="name" value="UnLoadedClassCount"/>
<entry key="lastsampletime">
<number>1300726989505</number>
</entry>
</map>
</entry>
<entry key="totalloadedclass-count">
<map>
<entry key="unit" value="count"/>
<entry key="starttime">
<number>1300483924127</number>
</entry>
<entry key="count">
number>8682</number>
</entry>
<entry key="description" value="Total number of classes that have been
loaded since the Java virtual machine has started execution"/>
<entry key="name" value="TotalLoadedClassCount"/>
<entry key="lastsampletime">
<number>1300726989505</number>
</entry>
</map>
</entry>
<entry key="loadedclass-count">
<map>
<entry key="unit" value="count"/>
<entry key="starttime">
<number>1300483924126</number>
</entry><entry key="count">
<number>8521</number>
</entry>
<entry key="description" value="Number of classes currently loaded in
the Java virtual machine"/>
<entry key="name" value="LoadedClassCount"/>
<entry key="lastsampletime">
<number>1300726989505</number>
</entry>
</map>
</entry>
</map>
</entry>
<entry key="childResources">
<map/>
</entry>
</map>
</entry>
<entry key="message" value=""/>
<entry key="exit_code" value="SUCCESS"/>
<entry key="command" value="Monitoring Data"/>
</map>
HTML Resource Representation for Monitoring Objects
The format for the HTML representation of a resource for a monitoring object is a web page that provides the following information about the resource:
-
A list of the statistics that the resource provides.
-
A list of hypertext links to the children of the resource.
The following figure shows the web page for the REST resource that provides class loader statistics for the virtual machine for the Java platform.
Formats for Resource Representation of Log File Details
The Eclipse GlassFish REST interfaces represent resources for log file details in the following formats:
JSON Resource Representation for Log File Details
The general format for the JSON representation of a resource for log file details is as follows:
{
"records": [
record-list
]
}
The replaceable item in this format is the record-list, which is one or
more metadata sets separated by a comma (,
) that represent the log
records in the log file. For the format of each metadata set, see
JSON Representation of a Log Record in a Record List.
JSON Representation of a Log Record in a Record List
The JSON representation of a log record in a record list is as follows:
{
"recordNumber":record-number,
"loggedDateTimeInMS":logged-date,
"loggedLevel":"log-level",
"productName":"product-name",
"loggerName":"logger-name",
"nameValuePairs":"_ThreadID=thread-id;_ThreadName=thread-name;",
"messageID":"message-id",
"Message":"message-text"
}
The replaceable items in this format are as follows:
- record-number
-
A serial number in the form of a decimal integer that uniquely identifies the log record.
- logged-date
-
time when the record was created - a number of milliseconds from the epoch of
1970-01-01T00:00:00Z
. - log-level
-
The severity level of the message in the log record. For more information, see Setting Log Levels.
- product-name
-
The application that created the log message, for example,
GlassFish 7.0
. - logger-name
-
The logger name, which is usually a fully qualified name of the Java class owning the logger class that created the log record. For detailed information how to get names of logger classes used in Eclipse GlassFish, see Listing Loggers.
- thread-id
-
The numerical identifier of the thread that created the message.
- thread-name
-
The name of the thread that created the message.
- message-id
-
A unique identifier for the message. For messages from Eclipse GlassFish, this identifier consists of a module code and a numerical value, for example,
CORE5004
. AllSEVERE
andWARNING
messages and someINFO
messages from Eclipse GlassFish contain a message identifier. For more information, see the Eclipse GlassFish Error Message Reference. - message-text
-
The text of the log message.
Example JSON Resource Representation for Log File Details
This example shows the JSON representation of the resource for log file
details. 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/view-log/details
.
Line breaks and white space are added to enhance readability.
{
"records": [
{
"recordNumber":475,
"loggedDateTimeInMS":1300743782815,
"loggedLevel":"INFO",
"productName":"glassfish7",
"loggerName":"org.glassfish.admingui",
"nameValuePairs": "_ThreadID=25;_ThreadName=Thread-1;",
"messageID":"",
"Message":"Admin Console: Initializing Session Attributes..."
},
{
"recordNumber":474,
"loggedDateTimeInMS":1300728893368,
"loggedLevel":"INFO",
"productName":"glassfish7",
"loggerName":"jakarta.enterprise.system.core.com.sun.enterprise.v3.admin.adapter",
"nameValuePairs":"_ThreadID=238;_ThreadName=Thread-1;",
"messageID":"",
"Message":"The Admin Console application is loaded."
},
{
"recordNumber":473,
"loggedDateTimeInMS":1300728893367,
"loggedLevel":"INFO",
"productName":"glassfish7",
"loggerName":"jakarta.enterprise.system.core.com.sun.enterprise.v3.server",
"nameValuePairs":"_ThreadID=238;_ThreadName=Thread-1;",
"messageID":"CORE10010",
"Message":" Loading application __admingui done in 40,063 ms"
}
]
}
XML Resource Representation for Log File Details
The general format for the XML representation of a resource for log file details is as follows:
<records>
records
</records>
The replaceable item in this format is the records, which is one or more XML elements that represent the log records in the log file. For the format of each element, see XML Representation of a Log Record.
XML Representation of a Log Record
The XML representation of a log record is as follows:
<record loggedDateTimeInMS="logged-date" loggedLevel="log-level"
loggerName="logger-class-name" messageID="message-id"
nameValuePairs="_ThreadID=thread-id;_thread-name;" productName="product-name"
recordNumber="record-number"/>
The replaceable items in this format are as follows:
- logged-date
-
time when the record was created - a number of milliseconds from the epoch of
1970-01-01T00:00:00Z
. - log-level
-
The severity level of the message in the log record. For more information, see Setting Log Levels.
- logger-class-name
-
The fully qualified name of the Java class of the logger class that created the log message. Each component of Eclipse GlassFish provides its own logger class. For detailed information about the names of logger classes in Eclipse GlassFish, see Listing Loggers.
- message-id
-
A unique identifier for the message. For messages from Eclipse GlassFish, this identifier consists of a module code and a numerical value, for example,
CORE5004
. AllSEVERE
andWARNING
messages and someINFO
messages from Eclipse GlassFish contain a message identifier. For more information, see the Eclipse GlassFish Error Message Reference. - thread-id
-
The numerical identifier of the thread that created the message.
- thread-name
-
The name of the thread that created the message.
- product-name
-
The application that created the log message, for example,
GlassFish 7.0
. - record-number
-
A serial number in the form of a decimal integer that uniquely identifies the log record.
Example XML Resource Representation for Log File Details
This example shows the XML representation of the resource for log file
details. 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/view-log/details
.
Line breaks and white space are added to enhance readability.
<records>
<record loggedDateTimeInMS="1300743782815" loggedLevel="INFO"
loggerName="org.glassfish.admingui" messageID=""
nameValuePairs="_ThreadID=25;_ThreadName=Thread-1;"
productName="glassfish7" recordNumber="475"/>
<record loggedDateTimeInMS="1300728893368" loggedLevel="INFO"
loggerName="jakarta.enterprise.system.core.com.sun.enterprise.v3.admin.adapter"
messageID="" nameValuePairs="_ThreadID=238;_ThreadName=Thread-1;"
productName="glassfish7" recordNumber="474"/>
<record loggedDateTimeInMS="1300728893367" loggedLevel="INFO"
loggerName="jakarta.enterprise.system.core.com.sun.enterprise.v3.server"
messageid="core10010" nameValuePairs="_ThreadID=238;_ThreadName=Thread-1;"
productName="glassfish7" recordNumber="473"/>
</records>
Supported Content Types in Requests to REST Resources
The Eclipse GlassFish REST interfaces support the following types in the content-type header of a client request:
How to specify the type in the content-type header depends on how you
are sending the request. For example, if you are using the cURL utility,
specify the type through the -H
option as follows:
-
For JSON, specify
-H "Content-type: application/json"
. -
For XML, specify
-H "Content-type: application/xml"
. -
For form URL encoded, specify
-H "Content-type: application/x-www-form-urlencoded"
.
Log executed admin commands
It’s possible to log admin commands executed either using the asadmin CLI, Admin Console, or the REST interface.
To enable this logging, set the system property glassfish.commandlogger.logmode
on the DAS server to one of the following values:
-
ALL_COMMANDS
- will log all commands -
WRITE_COMMANDS
- will log all commands that modify server configuration -
INTERNAL_COMMANDS
- will log all commands that modify server configuration and also those that start with_
(internal commands) -
READ_WRITE_COMMANDS
- will log all commands that modify server configuration or return info about the configuration -
NO_COMMAND
- do not log any command, this is the default value if the property not specified
The log message will be logged using org.glassfish.extras.commandlogger.AdminCommandLogger
logger with INFO
level, and will contain:
-
name of the admin user that executed the command
-
name of the command
-
arguments to the command
The name and arguments can be copied and pasted to the asadmin CLI to repeat running the same command from the command line.
3 Administering Domains
This chapter provides procedures for administering domains in the
Eclipse GlassFish environment by using the asadmin
command-line utility.
The following topics are addressed here:
Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.
About Administering Domains
A domain contains a group of Eclipse GlassFish instances that are administered together. Each domain has a domain administration server (DAS) that hosts administrative applications. These concepts are explained in more detail in the following sections:
Eclipse GlassFish Instances
A Eclipse GlassFish instance is a single Virtual Machine for the Java platform (Java Virtual Machine or JVM machine) on a single node in which Eclipse GlassFish is running. A node defines the host where the Eclipse GlassFish instance resides. The JVM machine must be compatible with the Java Platform, Enterprise Edition (Jakarta EE).
Eclipse GlassFish instances form the basis of an application deployment.
Whenever a domain is created, Eclipse GlassFish creates a default
instance that is named server
. If a single instance meets your
requirements, you can use this instance for deploying applications
without the need to administer Eclipse GlassFish instances explicitly.
You administer the default instance when you administer its domain.
If you require multiple instances, you must administer the instances explicitly. For more information, see "Administering Eclipse GlassFish Instances" in Eclipse GlassFish High Availability Administration Guide.
For an instance, you can also create virtual servers. Virtual servers do not span instances. For many purposes, you can use virtual servers instead of multiple instances in operational deployments. Virtual servers enable you to offer, within a single instance, separate domain names, IP addresses, and some administration capabilities to organizations or individuals. To these users, a virtual server behaves like a dedicated web server, but without the hardware and basic web server maintenance.
For more information about virtual servers, see Administering Virtual Servers.
Domains for Administering Eclipse GlassFish
A domain is an administrative boundary that contains a group of Eclipse GlassFish instances that are administered together. Each instance can belong to only one domain. A domain provides a preconfigured runtime for user applications. Each domain has its own configuration data, log files, and application deployment areas that are independent of other domains. If the configuration is changed for one domain, the configurations of other domains are not affected.
Domains enable different organizations and administrators to share securely a single Eclipse GlassFish installation. Each organization or administrator can administer the instances in a single domain without affecting the instances in other domains.
At installation time, Eclipse GlassFish creates a default domain that is
named domain1
. After installation, you can create additional domains
as necessary.
When a domain is created, you are prompted for the administration user
name and password. If you accept the default, the user admin
is
created without password. To reset the administration password, see
"To Change an Administration Password" in Eclipse GlassFish Security Guide.
Domain Administration Server (DAS)
The domain administration server (DAS) is a specially designated Eclipse GlassFish instance that hosts administrative applications. The DAS is similar to any other Eclipse GlassFish instance, except that the DAS has additional administration capabilities. The DAS authenticates the administrator, accepts requests from administration tools, and communicates with other instances in the domain to carry out the requests from administration tools.
Each domain has its own DAS with a unique administration port number. The default administration port is 4848, but a different port can be specified when a domain is created.
The DAS has the master copy of the configuration data for all instances in a domain. If an instance is destroyed, for example, because a host failed, the instance can be re-created from the data in the DAS.
The DAS is the default Eclipse GlassFish instance in a domain and is
named server
. If a single instance meets your requirements, you can
use the DAS for deploying applications and for administering the domain.
The graphical Administration Console communicates with a specific DAS to administer the domain that is associated with the DAS. Each Administration Console session enables you to configure and manage only one domain. If you create multiple domains, you must start a separate Administration Console session to manage each domain.
Creating, Logging In To, and Deleting a Domain
The following topics are addressed here:
To Create a Domain
After installing Eclipse GlassFish 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.
-
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
subcommand -
Create a domain by using the
create-domain
subcommand. Information about the options for this subcommand is included in this help page. -
Type an admin user name and password for the domain. To avoid setting up an admin login, you can accept the default
admin
, with no password. Pressing Return also selects the default.
Example 3-1 Creating a Domain
This example creates a domain named domain1
. When you type the
command, you might be prompted for login information.
asadmin> create-domain --adminport 4848 domain1
Enter admin user name[Enter to accept default]>
Using port 4848 for Admin.
Default port 8080 for HTTP Instance is in use. Using 1161
Using default port 7676 for JMS.
Using default port 3700 for IIOP.
Using default port 8081 for HTTP_SSL.
Using default port 3820 for IIOP_SSL.
Using default port 3920 for IIOP_MUTUALAUTH.
Default port 8686 for JMX_ADMIN is in use. Using 1162
Distinguished Name of the self-signed X.509 Server Certificate is:
[CN=moonbeam.gateway.2wire.net,OU=GlassFish,O=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 Create a Domain From a Custom Template
A custom template enables you to customize the configuration of any domain that you create from the template.
-
Create a domain to use as the basis for the template. For more information, see To Create a Domain.
-
Use the
asadmin
utility or the Administration Console to configure the domain. Your configuration changes will be included in the template that you create from the domain. -
Copy the domain’s
domain.xml
file under a new name to the as-install/lib/templates
directory. A domain’sdomain.xml
file is located in the domain-dir/config
directory. -
In a plain text editor, edit the file that you copied to replace with tokens values that are to be substituted when a domain is created. Each token is identified as
%%%token-name%%%
, wheretoken-name
is- one of the following names
-
ADMIN_PORT
-
Represents the port number of the HTTP port or the HTTPS port for administration. This token is replaced with one of the following values in the command to create a domain from the template:
-
The value of the
--adminport
option -
The value of the
domain.adminPort
property
-
CONFIG_MODEL_NAME
-
Represents the name of the configuration that is created for the domain that is being created. This token is replaced with the string
server-config
. DOMAIN_NAME
-
Represents the name of the domain that is being created. This token is replaced with the operand of
create-domain
subcommand. HOST_NAME
-
Represents the name of the host on which the domain is being created. This token is replaced with the fully qualified host name of the host where the domain is being created.
HTTP_PORT
-
Represents the port number of the port that is used to listen for HTTP requests. This token is replaced with one of the following values in the command to create a domain from the template:
-
The value of the
--instanceport
option -
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
domain.instancePort
property
-
HTTP_SSL_PORT
-
Represents the port number of the port that is used to listen for secure HTTP requests. This token is replaced with one of the following values in the command to create a domain from the template:
-
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
http.ssl.port
property
-
JAVA_DEBUGGER_PORT
-
Represents the port number of the port that is used for connections to the Java Platform Debugger Architecture (JPDA) debugger. This token is replaced with one of the following values in the command to create a domain from the template:
-
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
java.debugger.port
property
-
JMS_PROVIDER_PORT
-
Represents the port number for the Java Message Service provider. This token is replaced with one of the following values in the command to create a domain from the template:
-
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
jms.port
property
-
JMX_SYSTEM_CONNECTOR_PORT
-
Represents the port number on which the JMX connector listens. This token is replaced with one of the following values in the command to create a domain from the template:
-
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
domain.jmxPort
property
-
ORB_LISTENER_PORT
-
Represents the port number of the port that is used for IIOP connections. This token is replaced with one of the following values in the command to create a domain from the template:
-
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
orb.listener.port
property
-
ORB_MUTUALAUTH_PORT
-
Represents the port number of the port that is used for secure IIOP connections with client authentication. This token is replaced with one of the following values in the command to create a domain from the template:
-
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
orb.mutualauth.port
property
-
ORB_SSL_PORT
-
Represents the port number of the port that is used for secure IIOP connections. This token is replaced with one of the following values in the command to create a domain from the template:
-
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
orb.ssl.port
property
-
OSGI_SHELL_TELNET_PORT
-
Represents the port number of the port that is used for connections to the Apache Felix Remote Shell. This shell uses the Felix shell service to interact with the OSGi module management subsystem. This token is replaced with one of the following values in the command to create a domain from the template:
-
A value that the
create-domain
subcommand calculates from the value of the--portbase
option -
The value of the
osgi.shell.telnet.port
property
-
SERVER_ID
-
Represents the name of the DAS for the domain that is being created. This token is replaced with the string
server
.For information about how these tokens are used in the default template, examine the as-install
/lib/templates/domain.xml
file.
-
Create the domain that you want to be based on a custom template. In the command to create the domain, pass the name of file that you edited in the previous step as the
--template
option of thecreate-domain
subcommand. -
Before starting the domain, verify that the domain’s
domain.xml
file is valid. Use theverify-domain-xml
subcommand for this purpose. Information about the options for this subcommand is included in the subcommand’s help page.
See Also
You can also view the full syntax and options of the subcommands by typing the following commands at the command line.
-
asadmin help create-domain
-
asadmin help verify-domain-xml
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
domain-root-dir, the default for which is as-install/domains
, is listed.
If there is more than one domain, the domain name must be specified.
To list domains that were created in other directories, specify the --domaindir
option.
List domains by using the list-domains
subcommand.
Example 3-2 Listing Domains
This example lists the domains in the default domain root 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
.
-
Determine the name of the domain that you are logging in to. To list the existing domains:
asadmin list-domains
-
Log in to the domain by using the
login
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" in Eclipse GlassFish Security Guide.
To Delete a Domain
Use the delete-domain
subcommand to delete an existing domain from a
server. Only the root user or the operating system user who is
authorized to administer the domain can run this subcommand.
Before You Begin
A domain must be stopped before it can be deleted.
-
List domains by using the
list-domains
subcommand. -
If necessary, notify domain users that the domain is being deleted.
-
Ensure that the domain you want to delete is stopped. If needed, see To Stop a Domain.
-
Delete the domain by using the
delete-domain
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
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
domain root 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 Eclipse GlassFish:
|
This subcommand is supported in local mode only.
Start a domain by using the start-domain
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
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 Eclipse GlassFish:
|
-
If necessary, notify users that you are going to stop the domain.
-
Stop the domain by using the
stop-domain
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
subcommand followed by the start-domain
subcommand.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Restart the domain by using the
restart-domain
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 DAS or a Eclipse GlassFish Instance for Automatic Restart
Use the create-service
subcommand in local mode to configure your
system to automatically restart a domain administration server (DAS) or
a Eclipse GlassFish instance. Eclipse GlassFish enables you to configure a
DAS or an instance for automatic restart on the following operating
systems:
-
Windows
-
Linux
-
Oracle Solaris
To ensure that automatic restart functions correctly on Windows, you must prevent service shutdown when a user logs out.
The following topics are addressed here:
To Configure a DAS or an Instance for Automatic Restart on Windows
On Windows systems, the create-service
subcommand creates a Windows
service to represent the DAS or instance. The service is created in the
disabled state. After this subcommand creates the service, you must use
the Windows Services Manager or the Windows Services Wrapper to start,
stop, uninstall, or install the service. To administer the service from
the Windows command line, use the sc.exe
tool.
This subcommand must be run as the OS-level administrator user.
-
Create the service by using the
create-service
subcommand. -
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
sc.exe
tool, type:C:\> sc start domain1
If you are using the
sc.exe
tool to administer the service, use the tool as follows:-
To obtain information about the service, use the
sc query
command. -
To stop the service, use the
sc stop
command. -
To uninstall the service, use the
sc delete
command.
-
Example 3-10 Creating a Service to Restart a DAS Automatically on Windows
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 Eclipse GlassFish
Domain Directory: C:\glassfish7\glassfish\domains\domain1
Configuration file for Windows Services Wrapper: C:\glassfish7\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:\glassfish7\glassfish\domains\domain1\bin\domain1Service.exe start
Stop Command: C:\glassfish7\glassfish\domains\domain1\bin\domain1Service.exe stop
Uninstall Command: C:\glassfish7\glassfish\domains\domain1\bin\domain1Service.exe
uninstall
Install Command: C:\glassfish7\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.
Example 3-11 Querying the Service to Restart a DAS Automatically on Windows
This obtains information about the service for the default domain on a system that is running Windows.
C:\> sc query domain1
SERVICE_NAME: domain1
TYPE : 10 WIN32_OWN_PROCESS
STATE : 1 STOPPED
WIN32_EXIT_CODE : 1077 (0x435)
SERVICE_EXIT_CODE : 0 (0x0)
CHECKPOINT : 0x0
WAIT_HINT : 0x0
To Configure a DAS or an Instance for Automatic Restart on Linux
On Linux systems, the create-service
subcommand creates a
System-V-style initialization script
/etc/init.d/GlassFish_`domain-or-instance-name and installs a link to
this script in any `/etc/rc`N
.d` directory that is present, where N is
0
, 1
, 2
, 3
, 4
, 5
, 6
, and S
. After this subcommand
creates the script, you must use this script to start, stop, or restart
the domain or instance.
The script automatically restarts the domain or instance only during a reboot. If the domain or instance is stopped, but the host remains running, the domain or instance is not restarted automatically. To restart the domain or instance, you must run the script manually.
You might no longer require the domain or instance to be automatically
restarted during a reboot. In this situation, use the operating system
to delete the initialization script and the link to the script that the
create-service
subcommand creates.
The create-service
subcommand must be run as the OS-level root user.
Create the service by using the create-service
subcommand.
Example 3-12 Creating a Service to Restart a DAS Automatically on Linux
This example creates a service for the default domain on a system that is running Linux.
asadmin> create-service
Found the Linux Service and successfully uninstalled it.
The Service was created successfully. Here are the details:
Name of the service:domain1
Type of the service:Domain
Configuration location of the service:/etc/init.d/GlassFish_domain1
User account that will run the service: root
You have created the service but you need to start it yourself.
Here are the most typical Linux commands of interest:
* /etc/init.d/GlassFish_domain1 start
* /etc/init.d/GlassFish_domain1 stop
* /etc/init.d/GlassFish_domain1 restart
For your convenience this message has also been saved to this file:
/export/glassfish7/glassfish/domains/domain1/PlatformServices.log
Command create-service executed successfully.
To Configure a DAS or an Instance for Automatic Restart on Oracle Solaris
On Oracle Solaris systems, the create-service
subcommand creates an
Oracle Solaris Service Management Facility (SMF) service that restarts a
DAS or an instance. 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, 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 or instance is stopped, SMF restarts it.
Before You Begin
To run the create-service
subcommand, you must have solaris.smf.*
authorization. For information about how to set the authorizations, see
the
useradd
(1M)
man page and the
usermod
(1M)
man page. 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
administration commands such as
svccfg
,
svcs
,
and
auths
must be available in the PATH.
If a particular Eclipse GlassFish domain or instance should not have default user privileges, modify the manifest of the service and reimport the service.
-
Create the service by using the
create-service
subcommand. -
After the service is created, enable the service by using the
svacdm enable
command.For example, to enable the SMF service for the default domain, type:
svacdm enable /appserver/domains/domain1
Example 3-13 Creating a Service to Restart a Domain Automatically on Oracle Solaris
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
/glassfish7/glassfish/domains
Manifest file location on the system:/var/svc/manifest/application
/GlassFish/domain1_home_gfuser_glassfish-installations_glassfish7
_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
For information about administering the service, see the following Oracle Solaris documentation:
-
"Managing Services (Overview)" in System Administration Guide: Basic Administration
-
"Managing Services (Tasks)" in System Administration Guide: Basic Administration
To Prevent Service Shutdown When a User Logs Out on Windows
By default, the Java Virtual Machine (VM) 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 Eclipse GlassFish service to shut down. To
prevent the service from shutting down when a user logs out, you must
set the -Xrs
Java VM option
(https://github.com/eclipse-ee4j/glassfishdocumentation
).
-
Ensure that the DAS is running.
-
Set the
-Xrs
Java VM option for the DAS. Use thecreate-jvm-options
subcommand for this purpose.asadmin> create-jvm-options -Xrs
-
Set the
-Xrs
Java VM option for the Java VM within which theasadmin
utility runs. To set this option, edit theasadmin.bat
file to add the-Xrs
option to the line that runs theadmin-cli.jar
file.-
In the as-install
\bin\asadmin.bat
file, edit the line to read as follows:%JAVA% -Xrs -jar "%~dp0..\modules\admin-cli.jar" %*
-
In the as-install-parent
\bin\asadmin.bat
file, edit the line to read as follows:%JAVA% -Xrs -jar "%~dp0..\glassfish\modules\admin-cli.jar" %*
-
-
If the Eclipse GlassFish service is running, restart the service for your changes to take effect.
Backing Up and Restoring a Domain
The following topics are addressed here:
To Back Up a Domain
Use the backup-domain
subcommand in local mode to make a backup of a
specified domain.
When you use the backup-domain
subcommand, Eclipse GlassFish creates a
ZIP file backup of all the files and subdirectories in the domain’s
directory, domain-root-dir/
domain-dir, except for the backups
subdirectory.
The backup-domain
subcommand provides several options to meet
particular needs, including:
-
--backupdir
to specify a directory in which to store the backup instead of the default domain-root-dir/
domain-dir/backups
. -
--description
to provide a description of the backup to be stored in the backup itself.-
Ensure that the domain is stopped .
The
backup-domain
subcommand operates only when the domain is stopped. -
Back up the domain by using the
backup-domain
subcommand. -
Restore the domain to its previous state, if necessary.
Start or resume the domain.
-
Example 3-14 Backing Up the Default Domain
This example makes a backup of the default domain, domain1
, storing
the backup file in /net/backups.example.com/glassfish
:
asadmin> backup-domain --backupdir /net/backups.example.com/glassfish domain1
Backed up domain1 at Mon Jan 17 08:16:22 PST 2011.
Command backup-domain executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help backup-domain
at the command line.
To Restore a Domain
Use the restore-domain
subcommand in local mode to use a backup file
to restore the files and subdirectories in a specified domain’s
directory.
The restore-domain
subcommand can use backup files created by the
backup-domain
subcommand and by automatic backup configurations, both
full backups and configuration-only backups. Automatic backup
configurations are available only in Eclipse GlassFish.
-
If necessary, notify domain users that the domain is being restored from backup.
-
Ensure that the domain is stopped.
The
restore-domain
subcommand operates only when the domain is stopped.To determine whether the domain is running, use the
list-domains
subcommand, as described in To List Domains.To stop the domain, use the
stop-domain
subcommand as described in To Stop a Domain. -
Restore backup files for a domain by using the
restore-domain
subcommand. -
Verify that the restore has succeeded.
-
If necessary, notify users that the domain has been restored and is available.
Example 3-15 Restoring the Default Domain
This example restores files for the default domain, domain1
, from the
most recent backup stored in a specified backup directory:
asadmin> restore-domain --backupdir /net/backups.example.com/glassfish domain1
Restored the domain (domain1) to /home/user1/glassfish7/glassfish/domains/domain1
Command restore-domain executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin restore-domain --help
at the command line.
To List Domain Backups
Use the list-backups
subcommand in local mode to display information
about backups of a specified domain stored in a specified backup
directory.
The list-backups
subcommand provides several options to meet
particular needs, including --backupdir
to specify a directory where
backups are stored instead of the default domain-dir/backups
.
List backups by using the list-backups
subcommand.
Example 3-16 Listing Backups of the Default Domain
This example lists the backups of the default domain, domain1
, that
are stored in the /net/backups.example.com/glassfish
directory:
asadmin> list-backups --backupdir /net/backups.example.com/glassfish domain1
CONFIG USER BACKUP DATE FILENAME
user1 Mon Jan 17 08:16:22 PST 2011 domain1_2011_01_17_v00001.zip
monthly-full user1 Wed Dec 01 00:00:00 PST 2010 domain1_2010_12_01_v00001.zip
monthly-full user1 Sat Jan 01 00:00:03 PST 2011 domain1_2011_01_01_v00001.zip
monthly-full user1 Tue Feb 01 00:00:01 PST 2011 domain1_2011_02_01_v00001.zip
Command list-backups executed successfully.
Note that this listing includes backups created automatically by a backup configuration. This feature is available only in Eclipse GlassFish.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-backups
at the command line.
Re-Creating the Domain Administration Server (DAS)
For mirroring purposes, and to provide a working copy of the DAS, you must have:
-
One host (olddashost) that contains the original DAS.
-
A second host (apphost) that contains a cluster with server instances running applications and catering to clients. The cluster is configured using the DAS on the first host.
-
A third host (newdashost) where the DAS needs to be re-created in a situation where the first host crashes or is being taken out of service.
You must maintain a backup of the DAS from the first host using the
|
Eclipse GlassFish includes |
To Migrate the DAS
The following steps are required to migrate the DAS from the first host (olddashost) to the third host (newdashost).
-
Install Eclipse GlassFish on newdashost just as it was installed on olddashost. This is required so that the DAS can be properly restored on newdashost without causing path conflicts.
-
Use the
restore-domain
subcommand to restore the latest backup file onto newdashost. For example:asadmin> restore-domain --backupdir /net/backups.example.com/glassfish
This example assumes that backups are stored in a network-accessible location. If this is not the case, manually copy the latest backup file from offline storage to a directory on newdashost. You can backup any domain. However, while re-creating the domain, the domain name should be same as the original.
-
Stop the domain on olddashost, if it is running.
-
Start the domain on newdashost by using the
start-domain
subcommand. For example:asadmin> start-domain domain1
-
If the domain on olddashost was centrally administered, set up centralized administration on newdashost. See "Enabling Centralized Administration of Eclipse GlassFish Instances" in Eclipse GlassFish High Availability Administration Guide for instructions.
-
Verify that instances on other hosts are visible to the new DAS on newdashost:
asadmin> list-instances --long
-
Change the DAS host values for properties under the node on apphost. In the file as-install
/nodes/
node-name/agent/config/das.properties
file, change theagent.das.host
property value to refer to newdashost instead of olddasnost. -
Use the new DAS to restart clusters and standalone instances on apphost: Restarting the clustered and standalone instances on apphost triggers their recognition of the new DAS on newdashost.
-
Use the
list-clusters
subcommand to list the clusters in the domain. -
Use the
stop-cluster
subcommand to stop each cluster. -
Use the
list-instances
subcommand to list the instances in the domain. -
Use the
restart-instance
subcommand to restart each standalone instance. -
Use the
start-cluster
subcommand to start each cluster. If the domain does not use centralized administration, use thestart-local-instance
subcommand to start the cluster instances on apphost.
-
-
Verify that instances on apphost are running:
asadmin> list-instances --long
-
Decommission and discontinue use of the DAS on olddashost.
Additional Domain Tasks
The following topics are addressed here:
To Display Domain Uptime
Use the uptime
subcommand in remote mode to display the length of time
that the domain administration server (DAS) has been running since it
was last started.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Display uptime by using the
uptime
subcommand.
Example 3-17 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
Eclipse GlassFish 7 requires Java SE 11 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. |
-
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 RI Downloads page .
-
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:
-
domain.xml
(java-home
insidejava-config
) -
asenv.conf
(settingAS_JAVA="path to java home"
) If a legal JDK is not found, a fatal error occurs and the problem is reported back to you. -
If necessary, change the JVM machine attributes for the domain. In particular, you might need to change the
JAVA_HOME
environment variable. For example, to change theJAVA_HOME
variable, type:as-install/bin/asadmin set "server.java-config.java-home=path-to-java-home"
To Change the Administration Port of a Domain
Use the set
subcommand in remote mode to change the administration
port of a domain.
The HTTP port or the HTTPS port for administration of a domain is
defined by the --adminport
option of the
create-domain
subcommand when the domain is created.
If this port must be reallocated for another purpose, change the port on
which the DAS listens for administration requests.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Set the port number to its new value. Use the
set
subcommand for this purpose.$ asadmin set server-config.network-config.network-listeners.network-listener.admin-listener.port=new-port-number
The new-port-number is the new value that you are setting for the port number.
After you set the port number to its new value, running the
list-domains
subcommand incorrectly reports that the DAS is not running. Thelist-domains
subcommand reports the correct state again only after you stop and restart the domain as explained in the steps that follow. -
Stop the domain, specifying the host on which the DAS is running and the old administration port number of the domain. You must specify the old port number because the DAS is still listening for administration requests on this port. If you omit the port number, the command fails because the
stop-domain
subcommand attempts to contact the DAS through the new port number.Only the options that are required to complete this task are provided in this step. For information about all the options for controlling the behavior of the domain, see the
stop-domain
(1) help page.$ asadmin --host host-name --port old-port-number stop-domain
- host-name
-
The name of the host on which the DAS is running. If you run the
stop-domain
subcommand on the host where the DAS is running, you must specify the actual host name and notlocalhost
. If you specifylocalhost
, thestop-domain
subcommand fails. - old-port-number
-
The value of administration port number of the domain before you changed it in the preceding step.
-
Start the domain.
Only the options that are required to complete this task are provided in this step. For information about all the options for controlling the behavior of the domain, see the
start-domain
(1) help page.$ start-domain [domain-name]
The domain-name is the name of the domain to start. If only one domain subdirectory is contained in the
domains
directory, you may omit this option.
Example 3-18 Changing the Administration Port of a Domain
This example changes the administration port of the domain domain1
from 4848 to 4849. The DAS is running on the host xk01.example.com
.
$ asadmin set
server-config.network-config.network-listeners.network-listener.admin-listener.port=4849
server-config.network-config.network-listeners.network-listener.admin-listener.port=4849
Command set executed successfully.
$ asadmin --host xk01.example.com --port 4848 stop-domain
Waiting for the domain to stop ....
Command stop-domain executed successfully.
$ asadmin start-domain
Waiting for domain1 to start ........................
Successfully started the domain : domain1
domain Location: /export/glassfish7/glassfish/domains/domain1
Log File: /export/glassfish7/glassfish/domains/domain1/logs/server.log
Admin Port: 4849
Command start-domain executed successfully.
See Also
You can also view the full syntax and options of the subcommands by typing the following commands at the command line:
-
asadmin help create-domain
-
asadmin help set
-
asadmin help start-domain
-
asadmin help stop-domain
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
Eclipse GlassFish 7 environment by using the
asadmin
command-line utility.
The following topics are addressed here:
Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.
Administering JVM Options
The Java Virtual Machine is an interpretive computing engine responsible for running the byte codes in a compiled Java program. The virtual machine translates the Java byte codes into the native instructions of the host machine. Eclipse GlassFish, being a Java process, requires a virtual machine to run and support the Java applications running on it. JVM settings are part of an Eclipse GlassFish configuration.
The following topics are addressed here:
To Create JVM Options
Use the create-jvm-options
subcommand in remote mode to create JVM
options in the Java configuration or the profiler elements of the
domain.xml
file. If JVM options are created for a profiler, these
options are used to record the settings that initiate the profiler.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create JVM options by using the
create-jvm-options
subcommand.To create more than one JVM option, use a colon (:) to separate the options. If the JVM option itself contains a colon (:), use the backslash (\) to offset the colon delimiter.
Information about properties for the subcommand is included in this help page.
-
To apply your changes, restart Eclipse GlassFish. 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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List JVM options by using the
list-jvm-options
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
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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List JVM options by using the
list-jvm-options
subcommand. -
If necessary, notify users that the JVM option is being deleted.
-
Delete JVM options by using the
delete-jvm-options
subcommand.To remove more than one JVM option, use a colon (:) to separate the options. If the JVM option itself contains a colon, use the backslash (\) to offset the colon delimiter.
-
To apply your changes, restart Eclipse GlassFish. 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 instance, including the domain
administration server (DAS). You can generate the following types of
reports: summary (default), class, thread, log.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Generate the report by using the
generate-jvm-report
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
A server instance is tied to a particular profiler by the profiler
element in the Java configuration. If JVM options are created for a
profiler, the options are used to record the settings needed to activate
a particular profiler. Use the create-profiler
subcommand in remote
mode to create the profiler element in the Java configuration.
Only one profiler can exist. If a profiler already exists, you receive an error message that directs you to delete the existing profiler before creating a new one.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create a profiler by using the
create-profiler
subcommand.Information about properties for the subcommand is included in this help page.
-
To apply your changes, restart Eclipse GlassFish.
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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Delete the profiler by using the
delete-profiler
subcommand. -
To apply your changes, restart Eclipse GlassFish.
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.
5 Administering Thread Pools
This chapter provides procedures for administering thread pools in the
Eclipse GlassFish 7 environment by using the
asadmin
command-line utility.
The following topics are addressed here:
Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.
About Thread Pools
The Virtual Machine for the Java platform (Java Virtual Machine) or JVM machine) can support many threads of execution simultaneously. To help performance, Eclipse GlassFish 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 Eclipse GlassFish receives a request, it assigns the request to a free thread from the thread pool. The thread executes the client’s requests and returns results. For example, if the request needs to use a system resource that is currently busy, the thread waits until that resource is free before allowing the request to use that resource.
Configuring Thread Pools
You can specify the minimum and maximum number of threads that are reserved for requests from applications. The thread pool is dynamically adjusted between these two values.
The following topics are addressed here:
To Create a Thread Pool
Use the create-threadpool
subcommand in remote mode to create a thread
pool.
The minimum thread pool size that is specified signals the server to allocate at least that many threads in reserve for application requests. That number is increased up to the maximum thread pool size that is specified. Increasing the number of threads available to a process allows the process to respond to more application requests simultaneously.
If one resource adapter or application occupies all the Eclipse GlassFish threads, thread starvation might occur. You can avoid this by dividing the Eclipse GlassFish threads into different thread pools.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create a new thread pool by using the
create-threadpool
subcommand.Information about options for the subcommand is included in this help page.
-
To apply your changes, restart Eclipse GlassFish.
See To Restart a Domain.
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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the existing thread pools by using the
list-threadpools
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.
-
List the existing thread pools by using the
list-threadpools
subcommand. -
Modify the values for a thread pool by using the
set
subcommand.The thread pool is identified by its dotted name.
-
To apply your changes, restart Eclipse GlassFish.
See To Restart a Domain.
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. [source]
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.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the existing thread pools by using the
list-threadpools
subcommand. -
Delete the specified thread pool by using the
delete-threadpool
subcommand. -
To apply your changes, restart Eclipse GlassFish.
See To Restart a Domain.
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.
6 Administering Web Applications
This chapter explains how to administer web applications in the Eclipse GlassFish 7 environment.
The following topics are addressed here:
Instructions for accomplishing some of these tasks by using the Administration Console are contained in the Administration Console online help.
Invoking a Servlet by Alternate Means
You can call a servlet deployed to Eclipse GlassFish by using a URL in a browser or embedded as a link in an HTML or JSP file. The format of a servlet invocation URL is as follows:
http://server:port/context-root/servlet-mapping?name=value
The following table describes each URL section.
Table 6-1 URL Fields for Servlets Within an Application
URL element | Description |
---|---|
server`:`port |
The IP address (or host name) and optional port number. To access the default web module for a virtual server, specify only this URL section. You do not need to specify the context-root or servlet-name unless you also wish to specify name-value parameters. |
context-root |
For an application, the context root is defined in the For both applications and individually deployed web modules, the default
context root is the name of the WAR file minus the |
servlet-mapping |
The |
|
Optional request parameters. |
Example 6-1 Invoking a Servlet With a URL
In this example, localhost
is the host name, MortPages
is the
context root, and calcMortgage
is the servlet mapping.
http://localhost:8080/MortPages/calcMortgage?rate=8.0&per=360&bal=180000
Example 6-2 Invoking a Servlet From Within a JSP File
To invoke a servlet from within a JSP file, you can use a relative path. For example:
<jsp:forward page="TestServlet"/><jsp:include page="TestServlet"/>
Changing Log Output for a Servlet
ServletContext.log
messages are sent to the server log. By default,
the System.out
and System.err
output of servlets are sent to the
server log. During startup, server log messages are echoed to the
System.err
output. Also by default, there is no Windows-only console
for the System.err
output.
You can change these defaults using the Administration Console Write to
System Log box. If this box is checked, System.out
output is sent to
the server log. If it is unchecked, System.out
output is sent to the
system default location only.
Defining Global Features for Web Applications
You can use the default-web.xml
file to define features such as
filters and security constraints that apply to all web applications.
For example, directory listings are disabled by default for added
security. To enable directory listings in your domain’s
default-web.xml
file, search for the definition of the servlet whose
servlet-name
is equal to default
, and set the value of the
init-param
named listings
to true
. Then restart the server.
<init-param>
<param-name>listings</param-name>
<param-value>true</param-value>
</init-param>
If listings
is set to true
, you can also determine how directory
listings are sorted. Set the value of the init-param
named sortedBy
to NAME
, SIZE
, or LAST_MODIFIED
. Then restart the server.
<init-param>
<param-name>sortedBy</param-name>
<param-value>LAST_MODIFIED</param-value>
</init-param>
The mime-mapping
elements in default-web.xml
are global and
inherited by all web applications. You can override these mappings or
define your own using mime-mapping
elements in your web application’s
web.xml
file. For more information about mime-mapping
elements, see
the Servlet specification.
You can use the Administration Console to edit the default-web.xml
file, or edit the file directly using the following steps.
To Use the default-web.xml
File
-
Place the JAR file for the filter, security constraint, or other feature in the domain-dir
/lib
directory. -
Edit the domain-dir
/config/default-web.xml
file to refer to the JAR file. -
To apply your changes, restart Eclipse GlassFish.
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 Eclipse GlassFish, you can front Eclipse GlassFish with Apache HTTP Server.
You can also use mod_jk
directly at the JSP/servlet engine for load
balancing. For more information about configuring mod_jk
and Apache
HTTP Server for load balancing with Eclipse GlassFish 7 refer to
"Configuring HTTP Load Balancing" in Eclipse GlassFish High Availability Administration Guide.
The following topics are addressed here:
To Enable mod_jk
You can front Eclipse GlassFish with Apache HTTP Server by enabling the
mod_jk
protocol for one of Eclipse GlassFish’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 Eclipse GlassFish 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
.
-
Install Apache HTTP Server and
mod_jk
.-
For information on installing Apache HTTP Server, see
http://httpd.apache.org/docs/2.2/install.html
. -
For information on installing
mod_jk
, seehttp://tomcat.apache.org/connectors-doc/webserver_howto/apache.html
.
-
-
Configure the following files:
-
apache2/conf/httpd.conf
, the main Apache configuration file -
apache2/conf/workers.properties
Example 6-4 and Example 6-5 provide examples of configuring these two files.
-
-
Start Apache HTTP Server (
httpd
). -
Start Eclipse GlassFish with at least one web application deployed.
In order for the
mod_jk
-enabled network listener to start listening for requests, the web container must be started. Normally, this is achieved by deploying a web application. -
Create a jk-enabled network listener by using the
create-network-listener
subcommand.asadmin> create-network-listener --protocol http-listener-1 \ --listenerport 8009 --jkenabled true jk-connector
-
If you are using the
glassfish-jk.properties
file to use non-default values of attributes described athttp://tomcat.apache.org/tomcat-5.5-doc/config/ajp.html
), set thejk-configuration-file
property of the network listener to the fully-qualified file name of theglassfish-jk.properties
file.asadmin> set server-config.network-config.network-listeners.network-listener.\ jk-connector.jk-configuration-file=domain-dir/config/glassfish-jk.properties
-
If you expect to need more than five threads for the listener, increase the maximum threads in the
http-thread-pool
pool:asadmin> set configs.config.server-config.thread-pools.thread-pool.\ http-thread-pool.max-thread-pool-size=value
-
To apply your changes, restart Eclipse GlassFish.
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
. In
this example, mod_jk
used as a simple pass-through.
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
that is set for mod_jk
. This
workers.properties
file is referenced in the second line of
Example 6-4
# 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 Eclipse GlassFish
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 Eclipse GlassFish
instance that is front-ended by the Apache load balancer must be
configured with a unique jvmRoute
system property.
-
On each of the instances, perform the steps in To Enable
mod_jk
.If your instances run on the same machine, you must choose different JK ports. The ports must match
worker.worker*.port
in yourworkers.properties
file. See the properties file in Example 6-5. -
On each of the instances, create the
jvmRoute
system property of Eclipse GlassFish by using thecreate-jvm-options
subcommand.Use the following format:
asadmin> create-jvm-options "-DjvmRoute=/instance-worker-name"/
where instance-worker-name is the name of the worker that you defined to represent the instance in the
workers.properties
file. -
To apply your changes, restart Apache HTTP Server and Eclipse GlassFish.
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 Eclipse GlassFish, you must first
generate a Secure Socket Layer (SSL) self-signed certificate on the
Apache HTTP Server with the mod_ssl
module. The tasks include
generating a private key, a Certificate Signing Request (CSR), a
self-signed certificate, and configuring SSL-enabled virtual hosts.
Before You Begin
The mod_jk
connector must be enabled.
-
Generate the private key as follows:
openssl genrsa -des3 -rand file1:file2:file3:file4:file5 -out server.key 1024
where
file1:file2:
and so on represents the random compressed files. -
Remove the pass-phrase from the key as follows:
openssl rsa -in server.key -out server.pem
-
Generate the CSR is as follows:
openssl req -new -key server.pem -out server.csr
Enter the information you are prompted for.
-
Generate a temporary certificate as follows:
openssl x509 -req -days 60 -in server.csr -signkey server.pem -out server.crt
This temporary certificate is good for 60 days.
-
Create the
http-ssl.conf
file under the/etc/apache2/conf.d
directory. -
In the
http-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 http-ssl.conf
File for mod_jk
Security
A basic SSL-enabled virtual host will appear in the http-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 Eclipse GlassFish
This procedure does not enable SSL transfer between mod_jk
and
Eclipse GlassFish. It enables mod_jk
to forward SSL-encrypted
information from the browser to Eclipse GlassFish.
Before You Begin
The self-signed certificate must be configured.
-
Perform the steps in To Enable
mod_jk
. -
Start another Eclipse GlassFish with at least one web application deployed.
In order for the
mod_jk
-enabled network listener to start listening for requests, the web container must be started. Normally, this is achieved by deploying a web application. -
Follow instructions from To Configure an HTTP Listener for SSL on the
mod_jk
connector.Use the following format:
asadmin> create-ssl --type http-listener --certname sampleCert new-listener
-
Add the following directives in the
httpd.conf
file under the/etc/apache2/conf.d
directory:# Should mod_jk send SSL information (default is On) JkExtractSSL On # What is the indicator for SSL (default is HTTPS) JkHTTPSIndicator HTTPS # What is the indicator for SSL session (default is SSL_SESSION_ID) JkSESSIONIndicator SSL_SESSION_ID # What is the indicator for client SSL cipher suit (default is SSL_CIPHER ) JkCIPHERIndicator SSL_CIPHER # What is the indicator for the client SSL certificated? (default is SSL_CLIENT_CERT ) JkCERTSIndicator SSL_CLIENT_CERT
-
To apply your changes, restart Apache HTTP Server and Eclipse GlassFish.
Administering mod_proxy_ajp
The Apache Connector mod_proxy_ajp
can be used to connect the web
container with Apache HTTP Server. By using mod_proxy_ajp
, you can
front Eclipse GlassFish with Apache HTTP Server.
To Enable mod_proxy_ajp
You can front Eclipse GlassFish with Apache HTTP Server and its
mod_proxy_ajp
connector by enabling the AJP protocol for one of
Eclipse GlassFish’s network listeners, as described in this procedure. A
typical use for mod_proxy_ajp
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 Eclipse GlassFish back-end instance.
-
Install Apache HTTP Server.
For information on installing Apache HTTP Server, see
http://httpd.apache.org/docs/2.2/install.html
. -
Configure
apache2/conf/httpd.conf
, the main Apache configuration file.For example:
LoadModule proxy_module /usr/lib/httpd/modules/mod_proxy.so LoadModule proxy_ajp_module /usr/lib/httpd/modules/mod_proxy_ajp.so Listen 1979 NameVirtualHost *:1979 <VirtualHost *:1979> ServerName localhost ErrorLog /var/log/apache2/ajp.error.log CustomLog /var/log/apache2/ajp.log combined <Proxy *> AddDefaultCharset Off Order deny,allow Allow from all </Proxy> ProxyPass / ajp://localhost:8009/ ProxyPassReverse / ajp://localhost:8009/ </VirtualHost>
-
Start Apache HTTP Server (
httpd
). -
Create a jk-enabled network listener by using the
create-network-listener
subcommand.asadmin> create-network-listener --protocol http-listener-1 \ --listenerport 8009 --jkenabled true jk-connector
-
If you expect to need more than five threads for the listener, increase the maximum threads in the
http-thread-pool
pool:asadmin> set configs.config.server-config.thread-pools.thread-pool.\ http-thread-pool.max-thread-pool-size=value
-
To apply your changes, restart Eclipse GlassFish.
See To Restart a Domain.
See Also
For more information on Apache, see http://httpd.apache.org/
.
For more information on the Apache mod_proxy_ajp
Connector, see
http://httpd.apache.org/docs/2.1/mod/mod_proxy.html
and
http://httpd.apache.org/docs/2.1/mod/mod_proxy_ajp.html
.
For more information on the AJP protocol, see
http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html
.
To Load Balance Using mod_proxy_ajp
and Eclipse GlassFish
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. In the Eclipse GlassFish context, load balancing is most frequently used to distribute work among the instances in a Eclipse GlassFish cluster.
To configure load balancing using mod_proxy_ajp
, you must use the
mod_proxy_balancer
Apache module in addition to mod_proxy_ajp
.
In order to support stickiness, the mod_proxy_balancer
load balancer
relies on a jvmRoute
system property that is included in any
JSESSIONID
received by the load balancer. Consequently, every
Eclipse GlassFish instance that is front-ended by the Apache load
balancer must be configured with a unique jvmRoute
system property.
-
Install Apache HTTP Server.
For information on installing Apache HTTP Server, see
http://httpd.apache.org/docs/2.2/install.html
. -
Configure
apache2/conf/httpd.conf
, the main Apache configuration file.For example:
LoadModule proxy_module /usr/lib/httpd/modules/mod_proxy.so LoadModule proxy_ajp_module /usr/lib/httpd/modules/mod_proxy_ajp.so LoadModule proxy_balancer_module /usr/lib/httpd/modules/mod_proxy_balancer.so # Forward proxy needs to be turned off ProxyRequests Off # Keep the original Host Header ProxyPreserveHost On <Proxy *> Order deny,allow Deny from all Allow from localhost </Proxy> # Each BalancerMember corresponds to an instance in the Eclipse GlassFish # cluster. The port specified for each instance must match the ajp port # specified for that instance. <Proxy balancer://localhost> BalancerMember ajp://localhost:8009 BalancerMember ajp://localhost:8010 BalancerMember ajp://localhost:8011 </Proxy>
-
Start Apache HTTP Server (
httpd
). -
In Eclipse GlassFish, use the
create-network-listener
subcommand to create a jk-enabled network listener targeted to the cluster.For example:
asadmin> create-network-listener --jkenabled true --target cluster1 \ --protocol http-listener-1 --listenerport ${AJP_PORT} jk-listener
In this example,
cluster1
is the name of the cluster andjk-listener
is the name of the new listener. -
If you expect to need more than five threads for the listener, increase the maximum threads in the
http-thread-pool
pool:asadmin> set configs.config.cluster1-config.thread-pools.thread-pool.\ http-thread-pool.max-thread-pool-size=value
-
Use the
create-jvm-options
subcommand to create thejvmRoute
property targeted to the cluster.For example:
asadmin> create-jvm-options --target cluster1 \ "-DjvmRoute=\${AJP_INSTANCE_NAME}"
-
Use the
create-system-properties
subcommand to define theAJP_PORT
andAJP_INSTANCE_NAME
properties for each of the instances in the cluster, making sure to match the port values you used in Step 2 when specifying the load balancer members.For example:
asadmin> create-system-properties --target instance1 AJP_PORT=8009 asadmin> create-system-properties --target instance1 \ AJP_INSTANCE_NAME=instance1 asadmin> create-system-properties --target instance2 AJP_PORT=8010 asadmin> create-system-properties --target instance2 \ AJP_INSTANCE_NAME=instance2 asadmin> create-system-properties --target instance3 AJP_PORT=8011 asadmin> create-system-properties --target instance3 \ AJP_INSTANCE_NAME=instance3
In this example,
instance1
,instance2
andinstance3
are the names of the Eclipse GlassFish instances in the cluster. -
To apply your changes, restart Eclipse GlassFish.
See To Restart a Domain.
7 Administering the Logging Service
This chapter provides instructions on how to configure logging and how to view log information in the Eclipse GlassFish 7 environment.
The following topics are addressed here:
About Logging
Logging is the process by which Java Virtual Machine captures information about events that occur, such as important method calls, reaching states, or even configuration errors, security failures, or server malfunction.
This data is recorded in log files and is usually the first source of information when problems occur. Analyzing the log files can help you to follow events that occur in the server runtime and determine the overall health of the server.
Although application components can use other logging frameworks as
SLF4J
or LOG4J2
,
we recommend to use the
Java Util Logging Framework
or even better it’s latest facade
System.Logger
.
Logs may contain sensitive information. Despite the Eclipse GlassFish in default configuration doesn’t log any passwords, before you share logs with anyone else you should verify that you don’t compromise your system by any information contained in logs, especially if you configured more verbose log levels. |
Log Manager
Log Manager is a service responsible for the logging system. The service is initialized on JVM startup. After it’s first usage it cannot be changed until the JVM is restarted, but it can be reconfigured. Eclipse GlassFish now comes with customized log manager.
Level
Level is the key feature of the logging system. Every JUL Logger has an internal integer value representing severity. Levels are set to
-
Log Record as the severity level of the record.
-
Logger as the minimal severity level processed by the logger. Log record with lower severity is ignored.
-
Handler as the minimal severity level processed by the handler. Log record with lower severity is ignored.
There are following predefined levels; however the real usage depends on developers:
-
ALL - Special level used by loggers and handlers to declare that they accept all levels.
-
SEVERE - Used for serious errors.
-
WARNING - Used for log records providing an information about some hazards which can be handled by the application or they can even lead to a severe state.
-
INFO - Used to log some important information useful even for the user.
-
CONFIG - Used for providing an information related to a configuration.
-
FINE - Level for tracing. Used for providing an information about internal behavior of the java application, but still not so detailed.
-
FINER - Level for tracing. More detailed information, for example usages of
Logger.entering
andLogger.exiting
methods. -
FINEST - Level for tracing. Usually very verbose messages slowing down the system but providing a complete information what is going on.
-
OFF - Special level used by loggers and handlers to declare that they ignore all levels.
Some projects define custom levels, but at this time it is rather rare.
Log Record
Log Record is an object created by a Logger or it’s caller and sent to the hierarchy of loggers and handlers which will process it. Every time you use the Logger object to log a message with a level passing configured level filters, one LogRecord instance is created and processed.
Logger
Logger is a facade of the logging system. It is transparent so it can be initialized as a constant. Logger name is usually same as the full name of the class which created it, but specialized loggers can be used too.
Loggers are organized in a tree, so the log record is usually processed by the logger which accepted or created it, then passed to the parent logger (parent package), it’s parent, etc. unless it is configured to not to do so.
The logger log level specifies a severity level to filter what is important for the user. There are several special loggers:
-
root logger - uses an empty string as a name.
-
system root logger - uses an empty string as a name too, but is not accessible outside JDK, which uses it internally.
-
global logger - uses
global
as it’s name. It is not recommended to use it.
Handler
Handler is responsible for handling the record so it can print the record to the standard output, file, e-mail, network, etc. Handler have also it’s own level set. This level serves as a filter of incomming log records - usually it is not desired to send detailed messages to an e-mail, for example.
Default Configuration
The Configuration File
The DAS as well as each configuration, instance, and cluster has its own logging properties
file.
By default in an Eclipse GlassFish domain, logging properties files are created in the following locations:
Target | Default Location of Logging Properties File |
---|---|
DAS |
domain-dir |
A configuration |
domain-dir |
An instance |
domain-dir |
A cluster |
domain-dir |
For information about configuring logging properties, see Configuring the Logging Service.
The Server Log File
By default Eclipse GlassFish log records are captured in the server.log
file which
can be found in the logs
directory under the instance’s directory.
Each instance, managed server instance (that is, each cluster member),
and the domain administration server (DAS) has an individual server log file.
This file will contain also logs of deployed applications if they use Java Util Logging, System.Logger or any other facade mapped to this logging system in the backend.
Instance | Default Location |
---|---|
DAS |
domain-dir |
Each server instance |
instance-dir |
Cluster instance |
instance-dir |
For example, in a domain hosted on a given machine that includes a
cluster with two managed servers (ClusterServer1
and ClusterServer1
)
and a standalone instance (StandaloneServer
), the log files might be
arranged in the following directory structure. In this directory
structure, the server.log
file for the DAS is located in
domain-dir/logs
.
as-install-parent directory
glassfish/
domains/
domain-dir/
logs/
server.log
nodes/
hostname/
ClusterServer1/
logs/
server.log
ClusterServer2/
logs/
server.log
StandaloneServer/
logs/
server.log
The server.log
file uses the ODLLogFormatter log format by default and is
rolled to a new file after it’s size exceeds 100 Megabytes. If something
in server’s JVM prints to the standard output stream or standard
error stream, it is redirected to the server.log
file.
You can change the default name, location, formatting or management of a log
file by modifying the logging properties
file for the corresponding instance,
however we don’t recommend to change the location of the file as it may affect
availability of some services.
The Access Log File
The access.log
file serves to log all requests made to the HTTP service or
virtual server. This feature is disabled by default, but you can enable it by
using the asadmin set command, using Admininistration Console or the Admin REST API.
This logging feature is not persisted in logging.properties but in domain.xml, because it doesn’t use Java Util Logging framework but an internal implementation instead.
asadmin> get 'server.http-service.*' server.http-service.virtual-server.__asadmin.access-log=${com.sun.aas.instanceRoot}/logs/access server.http-service.virtual-server.__asadmin.access-logging-enabled=inherit ... server.http-service.virtual-server.server.access-log=${com.sun.aas.instanceRoot}/logs/access server.http-service.virtual-server.server.access-logging-enabled=inherit server.http-service.access-log.buffer-size-bytes=32768 server.http-service.access-log.format=%client.name% %auth-user-name% %datetime% %request% %status% %response.length% server.http-service.access-log.max-history-files=-1 server.http-service.access-log.rotation-enabled=true server.http-service.access-log.rotation-interval-in-minutes=1440 server.http-service.access-log.rotation-policy=time server.http-service.access-log.rotation-suffix=yyyy-MM-dd server.http-service.access-log.write-interval-seconds=300 server.http-service.access-logging-enabled=false
Standard Output Stream
When you start the server with the --verbose
argument, the server prints log
records to the standard output too.
The output is limited to just INFO levels and higher and uses the standard error stream,
but this can be switched to standard output stream too.
Log records are formatted to the Uniform Log Format] by default.
Configuring the Logging Service
You can either directly edit the logging.properties
file or use the asadmin command,
Administration Console or REST API.
On DAS, changes in the file have immediate effect with some small latency before they get applied.
For instances managed by nodes it is a bit more complicated and it depends
on the synchronization of the configuration with DAS.
If you edit |
Log Records
Because the automatic detection of caller class and method from stacktrace significantly affects
performance of the logging system, we added the org.glassfish.main.jul.classAndMethodDetection.enabled
property which affects the *.printSource
property of formatters.
-
If this key is set to true, GJULE will detect the caller class and method from stacktrace, which is quite expensive operation affecting logging throughput.
-
If it is set to false, GJULE will not perform such detection. Formatters which use
getSourceClassName
orgetSourceMethodName
of the record will receivenull
unless the log record has set these values explicitly. -
If the property is not set, GJULE makes the decision based on the (
.printSource
property) - if any formatter requires this feature, the feature is enabled. Note that the.printSource
property must be explicitly set to true inlogging.properties
. -
It is disabled otherwise.
Loggers
Changing the logger level is quite easy and it is a preferred way how to filter log records by their importance.
So for example if you want to get all records handled by the logging
system, you comment out all logger level settings except the root logger and set it’s level
to FINEST
.
.level=FINEST
Handlers
You can use all JUL features, but some of Eclipse GlassFish features depend on some settings
like the existence of the configured GlassFishLogHandler
and it’s server.log
file.
Also be careful when changing it’s configuration as it may affect the performance.
GlassFishLogHandler
The org.glassfish.main.jul.handler.GlassFishLogHandler
is used to handle persist log records
into the server.log
file. It is optimized for the best performance so logging would not
reduce the performance of the server instance and applications deployed to it.
Example:
org.glassfish.main.jul.handler.GlassFishLogHandler.buffer.capacity=10000 org.glassfish.main.jul.handler.GlassFishLogHandler.buffer.timeoutInSeconds=0 org.glassfish.main.jul.handler.GlassFishLogHandler.enabled=true org.glassfish.main.jul.handler.GlassFishLogHandler.encoding=UTF-8 org.glassfish.main.jul.handler.GlassFishLogHandler.file=${com.sun.aas.instanceRoot}/logs/server.log org.glassfish.main.jul.handler.GlassFishLogHandler.flushFrequency=1 org.glassfish.main.jul.handler.GlassFishLogHandler.formatter=org.glassfish.main.jul.formatter.ODLLogFormatter org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.excludedFields= org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.multiline=true org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.printSource=false org.glassfish.main.jul.handler.GlassFishLogHandler.level=ALL org.glassfish.main.jul.handler.GlassFishLogHandler.redirectStandardStreams=true org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.compress=false org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.maxArchiveFiles=0 org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.megabytes=100 org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.minutes=0 org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.rollOnDateChange=false
Basic Settings
-
enabled
-false
means that the handler will stay configured in the logging system, but it will ignore incoming records. Default istrue
. -
encoding
- file’s character encoding. Default isUTF-8
. -
file
- the output file; you can use also system options - default is${com.sun.aas.instanceRoot}/logs/server.log
-
flushFrequency
- count of records to be handled in a single batch. Default is 1. -
formatter
- a formatter class to be used for formatting log records as strings. Default value isorg.glassfish.main.jul.formatter.ODLLogFormatter
-
formatter.*
- can be used for custom settings of the formatter. This works only for ODLLogFormatter, UniformLogFormatter and OneLineFormatter. -
level
- Level used to filter log records. Less important log records will be ignored. Default isALL
. -
redirectStandardStreams
- iftrue
, which is default, everything printed to the standard output stream and standard error stream is processed by the handler as an INFO resp. ERROR log record. While using these streams is not recommended in Jakarta EE applications, it should be rather rare.
Receive Buffer
The GlassFishLogHandler
has a receive buffer for incomming log records to optimize throughput.
If the buffer is full and a logger tries to add another record, logger’s thread is blocked.
Then if the timeout is set to 0, the thread is blocked until there’s free capacity available
- if the handler cannot process records, it may be blocked forever.
But if you set the timeout to a positive value, and the thread is blocked for longer time,
the whole buffer is reset and added is just an error record describing what happened.
Despite this situation should not occur in standard situation, it may happen ie. when the file system stops working or is extremely slow.
-
buffer.capacity
- count of records in the receive buffer, default is 10000 log records. -
buffer.timeoutInSeconds
- maximal time for waiting. Default is 0 which means forever. The buffer is reset after timeout, which means that all unprocessible log records are lost.
Log File Rotation
The GlassFishLogHandler
can roll the output log file under following conditions:
-
if user forced him to do so, see To Rotate Log Files Manually for more
-
if the size of the file exceeded given limit
-
if the date changed
-
if the specified number of minutes have passed since the file was opened
The last two conditions are exclusive, the date change has higher priority.
The flushFrequency
parameter affects how many log records will be formatted
into the log file before the file is rolled out even after the file size exceeded it’s configured
limit.
The rotation means that the log file is renamed, so the new file name gets a current timestamp as a suffix. If there already is a file with the same name, the implementation tries to add another suffix with a counter until it finds a name which doesn’t exist yet.
drwxrwxr-x 14 admin admin 4096 jul 29 21:21 ../ -rw-rw-r-- 1 admin admin 2521 aug 3 18:18 server.log -rw-rw-r-- 1 admin admin 191391 jul 29 21:21 server.log_2022-07-29T21-21-54 -rw-rw-r-- 1 admin admin 24920 aug 3 18:18 server.log_2022-08-03T18-18-38
You can configure the logging service to change the default settings for log file rotation, as explained in Setting Log File Rotation.
This is a list of related configuration properties:
-
rotation.compress
- compress the rotated file using GZIP algorithm provided by JDK. Default is false. -
rotation.maxArchiveFiles
- maximal count of archived log files (excludes the active one). Default is 0, which means unlimited. -
rotation.limit.megabytes
- size of the file initiating rotation of the file. Default is 100 Megabytes. The final file will be slightly larger. -
rotation.limit.minutes
- number of minutes since the last rotation. Default is 0 (unlimited, disabled). -
rotation.rollOnDateChange
- if set totrue
rolls the file at midnight. Default isfalse
.
SimpleLogHandler
The org.glassfish.main.jul.handler.SimpleLogHandler
has similar targets as the
`ConsoleHandler
`,
with few differences:
-
can be configured to use STDOUT instead of STDERR
-
uses OneLineFormatter by default
The handler configuration properties:
-
encoding
- output character encoding. Default is null which means it will use the system default. -
formatter
- a formatter class to be used for formatting log records as strings. Default value isorg.glassfish.main.jul.formatter.OneLineFormatter
-
formatter.*
- can be used for custom settings of the formatter. This works only for ODLLogFormatter, UniformLogFormatter and OneLineFormatter. -
level
- Level used to filter log records. Less important log records will be ignored. UsesINFO
as a default. -
useErrorStream
- iffalse
, uses STDOUT instead of STDERR. Default istrue
.
Configuration example:
org.glassfish.main.jul.handler.SimpleLogHandler.formatter=org.glassfish.main.jul.formatter.OneLineFormatter org.glassfish.main.jul.handler.SimpleLogHandler.formatter.printSource=false org.glassfish.main.jul.handler.SimpleLogHandler.level=INFO org.glassfish.main.jul.handler.SimpleLogHandler.useErrorStream=true
SyslogHandler
The org.glassfish.main.jul.handler.SyslogHandler
is a special handler which is able to send
log records to the Unix Syslog facility. The prerequisity is that the Syslog service must
listen on the configured network endpoint.
See Syslog on Wikipedia.org
for more.
The handler configuration properties:
-
buffer.capacity
- count of records in the receive buffer. Default is 5000 log records. -
buffer.timeoutInSeconds
- maximal time for waiting. Default is 300. The buffer is reset after timeout, which means that all unprocessible log records are lost. -
enabled
-false
means that the handler will stay configured in the logging system, but it will ignore incoming records. Default istrue
. -
encoding
- output character encoding used to send data to the Syslog service. Default isUTF-8
. -
formatter
- a formatter class to be used for formatting log records as strings. Default value isjava.util.logging.SimpleFormatter
-
host
- a host name or IP address used of the UDP endpoint. Default is an autodetected name of the local host. -
level
- Level used to filter log records. Less important log records will be ignored. The default level isWARNING
. -
port
- a port of the Syslog UDP listener. Default is 514.
Configuration example:
org.glassfish.main.jul.handler.SyslogHandler.enabled=true org.glassfish.main.jul.handler.SyslogHandler.encoding=UTF-8 org.glassfish.main.jul.handler.SyslogHandler.formatter=java.util.logging.SimpleFormatter org.glassfish.main.jul.handler.SyslogHandler.host= org.glassfish.main.jul.handler.SyslogHandler.level=SEVERE org.glassfish.main.jul.handler.SyslogHandler.port=514
Formatters
Excluded Fields
Some of formatters support exclusion of some of fields. Currently is possible to exclude following fields:
-
tid
- Thread id and name -
levelValue
- Integer value of the log level.
ODLLogFormatter
The org.glassfish.main.jul.formatter.ODLLogFormatter
logs records in
the Oracle Diagnostic Loggging Format (ODL).
[2022-08-01T19:43:29.952291+02:00] [GlassFish 7.0] [INFO] [] [com.sun.enterprise.server.logging.LogManagerService] [tid: _ThreadID=1 _ThreadName=main] [levelValue: 800] [[ Using property file: /app/appservers/glassfish7/glassfish/domains/domain1/config/logging.properties]] [2022-08-01T19:43:29.986871+02:00] [GlassFish 7.0] [INFO] [NCLS-LOGGING-00009] [com.sun.enterprise.server.logging.LogManagerService] [tid: _ThreadID=1 _ThreadName=main] [levelValue: 800] [[ Running GlassFish Version: Eclipse GlassFish 7.0.0 (build master-b827-g71a6150 2022-08-01T11:18:51+0200)]]
The formatter has following properties:
-
excludedFields
- comma separated list of fields which should not be printed. None by default. See Excluded Fields -
fieldSeparator
- String separating fields. Space by default. -
multiline
- if set totrue
(default), the end of line character is inserted before the log message. -
printSequenceNumber
- if set totrue
, logs the sequence number of each log record. Default isfalse
. -
printSource
- if set totrue
, logs the class and method which created the log record. Default isfalse
. -
timestampFormat
- see theDateTimeFormatter
documentation. Default isISO-8601
timestamp with microseconds and time zone.
UniformLogFormatter
The org.glassfish.main.jul.formatter.UniformLogFormatter
logs records in
the Uniform Loggging Format.
[#|2022-08-02T18:16:29.677628+02:00|INFO|GlassFish 7.0|com.sun.enterprise.server.logging.LogManagerService|_ThreadID=1;_ThreadName=main;_LevelValue=800;| Using property file: /app/appservers/glassfish7/glassfish/domains/domain1/config/logging.properties|#] [#|2022-08-02T18:16:29.755356+02:00|INFO|GlassFish 7.0|com.sun.enterprise.server.logging.LogManagerService|_ThreadID=1;_ThreadName=main;_LevelValue=800;_MessageID=NCLS-LOGGING-00009;| Running GlassFish Version: Eclipse GlassFish 7.0.0 (build master-b827-g71a6150 2022-08-01T11:18:51+0200)|#]
The formatter has following properties:
-
excludedFields
- comma separated list of fields which should not be printed. None by default. See Excluded Fields -
fieldSeparator
- String separating fields. Space by default. -
multiline
- if set totrue
(default), the end of line character is inserted before the log message. -
printSequenceNumber
- if set totrue
, logs the sequence number of each log record. Default isfalse
. -
printSource
- if set totrue
, logs the class and method which created the log record. Default isfalse
. -
recordMarker.begin
- the prefix of the log record, default is[#|
. -
recordMarker.end
- the suffix of the log record, default is|#]
. -
timestampFormat
- see theDateTimeFormatter
documentation. Default isISO-8601
timestamp with microseconds and time zone.
OneLineFormatter
The org.glassfish.main.jul.formatter.OneLineFormatter
logs records in the following simple format:
22:50:43.174228 INFO main com.sun.enterprise.server.logging.LogManagerService Using property file: /app/appservers/glassfish7/glassfish/domains/domain1/config/logging.properties 22:50:43.266648 INFO main com.sun.enterprise.server.logging.LogManagerService Running GlassFish Version: Eclipse GlassFish 7.0.0 (build master-b827-g71a6150 2022-08-01T11:18:51+0200)
-
printSource
- if set totrue
(default), logs the class and method which created the log record while when set tofalse
it prefers the logger name. -
size.level
- number of characters taken by the level column. Default is 7. -
size.thread
- number of characters taken by the thread column. Default is 20. -
size.class
- number of characters taken by the class name column. Default is 60. -
timestampFormat
- see theDateTimeFormatter
documentation. Default isISO-8601
time with microseconds (not date, no timezone).
SimpleFormatter
The full name is java.util.logging.SimpleFormatter
. It is a default formatter provided by the JDK,
simple but very flexible. It’s most important property is format
. Read the
documentation of the SimpleFormatter class
for more.
Using Asadmin
Each instance in an Eclipse GlassFish domain has a dedicated server.log
file,
and each instance and cluster has its own logging.properties
file.
To configure logging for an instance or a cluster,
Eclipse GlassFish allows you target specific log
files or logging properties files when you do the following:
-
Set log levels
-
Rotate
server.log
files or compress them into a ZIP archive -
Change logging property attributes
-
List log levels or log attributes
The following subcommands optionally accept a target specification.
A target can be a configuration name, server name, cluster name, or instance name,
and is specified as either an operand or as a value
passed using the --target
option.
If no target is specified when using any of these subcommands, the default target is the DAS.
Subcommand | Description | Target Specification |
---|---|---|
Collects all available log files into a ZIP archive. |
|
|
Lists logging attributes in the logging properties file. |
target-name operand |
|
Lists the loggers in the logging properties file and their log levels. |
target-name operand |
|
Rotates the log file by renaming it and creating a new log file to store new messages. |
|
|
Sets the specified logging attributes in the logging properties file. |
|
|
Sets the log file formatter. |
|
|
Sets the log level for one or more loggers listed in the logging properties file. |
|
This section contains the following examples:
To Change the Location of the logging.properties File
You can set the name and location of the logging properties file by
setting the java.util.logging.config.file
system property.
You have to ensure that the output log file is always used by a single instance. In the default logging.properties it is ensured by using the ${com.sun.aas.instanceRoot} which always resolves to the instance’s root directory. Example: org.glassfish.main.jul.handler.GlassFishLogHandler.file=${com.sun.aas.instanceRoot}/logs/server.log |
-
Set the
java.util.logging.config.file
system property.asadmin create-jvm-options --target=server-config -Djava.util.logging.config.file=/logging.properties
Alternatively, you can use the Administration Console to set this system property.
-
To apply your change, restart all instances using this configuration. In our case it would be the DAS:
asadmin restart-domain
To Change the Location of the Log File
Even in complex domain you can always find the right logging.properties
file and
update it manually. But probably safer is to use an asadmin command to do that.
To change the name and location of the log file, first use the list-log-attributes
command
to obtain the current log attribute setting for the log file name and location.
Then use the set-log-attributes
command to specify the new name or location.
The default target for these two commands is the DAS. However, you can
optionally specify one of the following targets:
-
Configuration name — to target all instances or clusters that share a specific configuration name.
-
Server name — to target only a specific server.
-
Instance name — to target only a specific instance.
-
Cluster name — to target only a specific cluster.
-
Ensure that the DAS is running. Remote commands require a running server.
-
Use the
list-log-attributes
command in remote mode to obtain the current log attribute settings. The name and location of the log file is set with theorg.glassfish.main.jul.handler.GlassFishLogHandler.file
attribute of thelogging properties
file. Optionally you can target a configuration, server, instance, or cluster. If you do not specify a target, the log attribute settings for the DAS are displayed. -
Use the
set-log-attributes
command in remote mode to define a custom name or location of the log file. If you do not specify a target, the log file for the DAS is targeted by default. If you target a cluster, the name of the cluster log file for each member instance can be changed (the server log file name cannot).
Example 7-1 Changing the Name and Location of a Cluster’s Log File
This example changes the name of the cluster log file for Cluster1
to
cluster1.log
. Cluster1
has two server instances: ClusterServer1
and ClusterServer2
.
asadmin list-log-attributes Cluster1
handlers <org.glassfish.main.jul.handler.GlassFishLogHandler,org.glassfish.main.jul.handler.SimpleLogHandler,org.glassfish.main.jul.handler.SyslogHandler>
org.glassfish.main.jul.handler.GlassFishLogHandler.buffer.capacity <10000>
org.glassfish.main.jul.handler.GlassFishLogHandler.buffer.timeoutInSeconds <0>
org.glassfish.main.jul.handler.GlassFishLogHandler.enabled <true>
org.glassfish.main.jul.handler.GlassFishLogHandler.encoding <UTF-8>
org.glassfish.main.jul.handler.GlassFishLogHandler.file <${com.sun.aas.instanceRoot}/logs/server.log>
org.glassfish.main.jul.handler.GlassFishLogHandler.flushFrequency <1>
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter <org.glassfish.main.jul.formatter.ODLLogFormatter>
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.excludedFields <>
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.multiline <true>
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.printSource <false>
org.glassfish.main.jul.handler.GlassFishLogHandler.redirectStandardStreams <true>
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.compress <false>
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.megabytes <100>
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.minutes <0>
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.maxArchiveFiles <0>
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.rollOnDateChange <false>
org.glassfish.main.jul.handler.SimpleLogHandler.formatter <org.glassfish.main.jul.formatter.UniformLogFormatter>
org.glassfish.main.jul.handler.SimpleLogHandler.formatter.excludedFields <>
org.glassfish.main.jul.handler.SimpleLogHandler.formatter.printSource <false>
org.glassfish.main.jul.handler.SimpleLogHandler.useErrorStream <true>
org.glassfish.main.jul.handler.SyslogHandler.buffer.capacity <5000>
org.glassfish.main.jul.handler.SyslogHandler.buffer.timeoutInSeconds <300>
org.glassfish.main.jul.handler.SyslogHandler.enabled <false>
org.glassfish.main.jul.handler.SyslogHandler.encoding <UTF-8>
org.glassfish.main.jul.handler.SyslogHandler.formatter <java.util.logging.SimpleFormatter>
org.glassfish.main.jul.handler.SyslogHandler.host <>
org.glassfish.main.jul.handler.SyslogHandler.port <514>
Command list-log-attributes executed successfully.
asadmin set-log-attributes --target Cluster1 org.glassfish.main.jul.handler.GlassFishLogHandler.file=\${com.sun.aas.instanceRoot}/logs/cluster1.log
org.glassfish.main.jul.handler.GlassFishLogHandler.file logging attribute value set to ${com.sun.aas.instanceRoot}/logs/cluster1.log.
The logging attributes are saved successfully for cluster-config.
Command set-log-attributes executed successfully.
asadmin list-log-attributes ClusterServer1
...
org.glassfish.main.jul.handler.GlassFishLogHandler.file <${com.sun.aas.instanceRoot}/logs/cluster1.log>
...
asadmin list-log-attributes ClusterServer2
...
org.glassfish.main.jul.handler.GlassFishLogHandler.file <${com.sun.aas.instanceRoot}/logs/cluster1.log>
...
See Also
You can view the full syntax and options of these subcommands by typing
asadmin help list-log-attributes
and asadmin help set-log-attributes
at the command line.
Setting Log Levels
The log level determines the granularity of the message as it is described in the chapter Level.
When setting log levels, you can target a configuration, server, instance, or cluster.
Setting log levels is done by using the set-log-levels
subcommand.
Listing log levels is done by using the list-log-levels
subcommand.
The following topics are addressed here:
To List Logger Levels
Eclipse GlassFish provides the means to list all loggers and their log levels. Listing the loggers provides a convenient means to view current loggers and log levels either prior to or after making log level changes.
Use the list-log-levels
subcommand in remote mode to list the modules
and their current log levels.
The default target for this subcommand is the DAS.
However, you can optionally specify one of the following targets:
-
Configuration name — to target all instances or clusters that share a specific configuration name.
-
Server name — to target a specific server.
-
Instance name — to target a specific instance.
-
Cluster name — to target a specific cluster.
-
Ensure that the DAS is running. Remote subcommands require a running server.
-
List the existing module loggers and log levels by using the
list-log-levels
subcommand.
-
Example 7-2 Listing Logger Levels for DAS
This example shows a partial list of the existing loggers and their log levels in the DAS.
asadmin list-log-levels
MBeans <INFO>
com.sun.enterprise.glassfish.bootstrap <INFO>
com.sun.enterprise.glassfish <INFO>
com.sun.enterprise.security <INFO>
com.sun.webui <INFO>
jakarta.enterprise.admin.rest.client <INFO>
jakarta.enterprise.admin.rest.connector <INFO>
jakarta.enterprise.admin.rest <INFO>
jakarta.enterprise.bootstrap <INFO>
jakarta.enterprise.cluster.gms.admin <INFO>
jakarta.enterprise.cluster.gms.bootstrap <INFO>
jakarta.enterprise.cluster.gms <INFO>
jakarta.enterprise.concurrent <INFO>
jakarta.enterprise.config.api <INFO>
...
Command list-log-levels executed successfully.
Example 7-3 Listing Logger Levels for an Instance
This example shows a partial list of the loggers and log levels for the instance MyServer2
.
asadmin list-log-levels MyServer2
MBeans <INFO>
com.sun.enterprise.glassfish.bootstrap <INFO>
com.sun.enterprise.glassfish <INFO>
com.sun.enterprise.security <INFO>
com.sun.webui <INFO>
cz.acme.level <ALL>
jakarta.enterprise.admin.rest.client <INFO>
jakarta.enterprise.admin.rest.connector <INFO>
jakarta.enterprise.admin.rest <INFO>
jakarta.enterprise.bootstrap <INFO>
jakarta.enterprise.cluster.gms.admin <INFO>
jakarta.enterprise.cluster.gms.bootstrap <INFO>
jakarta.enterprise.cluster.gms <INFO>
jakarta.enterprise.concurrent <INFO>
jakarta.enterprise.config.api <INFO>
...
Command list-log-levels executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help list-log-levels
at the command line.
To Set the Logger Log Level
You will probably need to set logger levels most often.
Let’s imagine that you would need to set the most verbose logging of an application
using the org.acme
package (and logger names).
Logs may contain sensitive information. Despite the Eclipse GlassFish in default configuration doesn’t log any passwords, before you share logs with anyone else you should verify that you don’t compromise your system by any information contained in logs, especially if you configured more verbose log levels. |
Then you can edit the logging.properties
file directly, what can be quite
more complicated it you use more than one instance, see the warning.
Safer is to use the set-log-levels
subcommand:
Example 7-5 Changing the Logger Log Level for a Cluster
asadmin set-log-levels --target Cluster1 org.acme=ALL
org.acme package set with log level ALL.These logging levels are set for Cluster1.
Command set-log-levels executed successfully.
Example 7-5 Setting Log Levels for Multiple Loggers
The following example sets the log level for security and web container loggers in the DAS.
asadmin set-log-levels jakarta.enterprise.system.core.security=FINE\
:jakarta.enterprise.system.container.web=WARNING
jakarta.enterprise.system.core.security package set with log level FINE.jakarta.enterprise.system.container.web package set with log level WARNING.These logging levels are set for server.
Command set-log-levels executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help set-log-levels
at the command line.
To Set the Handler Log Level
The handler log level specifies a severity level filter to prevent overloading
of the handler. Default value is usually given by handler’s implementation
and reflect targets and expected throughput of the handler.
For example, you would not want to send all FINEST
LogRecords by e-mail,
but you would like to see them in a local log file.
Because JUL uses the same property syntax for Logger levels as
for Handler levels you can use both set-log-levels
and set-log-attributes
subcommands to get the same result (with a bit different syntax).
Both commands in remote mode.
The default target for this subcommand is the DAS.
However, you can optionally specify one of the following targets using the --target
option:
-
Configuration name — to target all instances or clusters that share a specific configuration name.
-
Server name — to target a specific server.
-
Instance name — to target a specific instance.
-
Cluster name — to target a specific cluster.
-
Ensure that the DAS is running.
-
Set the log level by using the
set-log-attributes
subcommand, specifying the log level of theorg.glassfish.main.jul.handler.GlassFishLogHandler
handler. For example:org.glassfish.main.jul.handler.GlassFishLogHandler <ALL>
Example 7-6 Changing the Handler Log Level
This example sets the log level for GlassFishLogHandler
in the DAS to INFO
:
asadmin set-log-attributes org.glassfish.main.jul.handler.GlassFishLogHandler.level=INFO
org.glassfish.main.jul.handler.GlassFishLogHandler.level logging attribute value set to INFO.
The logging attributes are saved successfully for server.
Command set-log-attributes executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help set-log-attributes
at the command line.
Setting the Log File Format
You can set the format for log records in log files. The following topics are addressed here:
To Set the Log File Format
Use the set-log-file-format
subcommand in remote mode to set the
formatter used by Eclipse GlassFish to format log records in log files.
This command is limited to the GlassFishLogHandler
settings.
You can also use the set-log-attributes
subcommand which is more flexible.
Log formats for all server instances in a cluster will be the same.
For information about log formats, see Formatters.
Changing the log format forces log rotation to avoid mixed format in the same file. |
-
Ensure that the DAS is running. Remote commands require a running server.
-
Set the formatter by using the
set-log-file-format
subcommand. -
To apply your change, restart affected instances or clusters with the synchronization enabled.
Example 7-7 Setting the Log File Format using set-log-file-format
This example sets the log file format to OneLineFormatter
for standalone instance
ManagedServer1
using the set-log-file-format
subcommand.
asadmin set-log-file-format --target ManagedServer1 org.glassfish.main.jul.formatter.OneLineFormatter
The log file formatter is set to org.glassfish.main.jul.formatter.OneLineFormatter for instance server.
Command set-log-file-format executed successfully.
Example 7-8 Setting the Log File Format using set-log-attributes
This example sets the log file format to ULF
for standalone instance
ManagedServer1
using the set-log-attributes
subcommand.
asadmin set-log-attributes --target ManagedServer1 \
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter=org.glassfish.main.jul.formatter.OneLineFormatter
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter logging attribute value set to org.glassfish.main.jul.formatter.OneLineFormatter.
The logging attributes are saved successfully for ManagedServer1-config.
Command set-log-attributes executed successfully.
See Also
You can view the full syntax and options of the set-log-file-format
subcommand by typing asadmin help set-log-file-format
at the command
line. You can view the full syntax and options of the
set-log-attributes
subcommand by typing
asadmin help set-log-attributes
at the command line.
To Exclude Fields in Logs
Use the set-log-attributes
subcommand in remote mode to exclude
specific name-value fields from log records. If the excludeFields
attribute is not specified, all name-value fields are included.
The following fields can be excluded:
-
tid
-
levelVal
-
Ensure that the DAS is running. Remote commands require a running server.
-
Exclude fields by using the
set-log-attributes
subcommand, specifying the attribute and the fields to exclude. -
To apply your change, restart Eclipse GlassFish.
Example 7-9 Excluding Fields in the ODLLogFormatter
This example excludes the tid
(thread ID and name) and levelValue
(numerical value of the Level)
name-value fields in log records for standalone instance ManagedServer1
:
asadmin set-log-attributes --target ManagedServer1 \
org.glassfish.main.jul.formatter.ODLLogFormatter.excludedFields=tid,levelValue
org.glassfish.main.jul.formatter.ODLLogFormatter.excludedFields logging attribute value set to tid,levelValue.
The logging attributes are saved successfully for ManagedServer1-config.
Command set-log-attributes executed successfully.
If there’s the same attribute of the handler’s |
Example 7-10 Excluding Fields in the GlassFishLogHandler
This example excludes the tid
(thread ID and name) and levelValue
(numerical value of the Level)
name-value fields in log records for standalone instance ManagedServer1
:
asadmin set-log-attributes --target ManagedServer1 \
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.excludedFields=tid,levelValue
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.excludedFields logging attribute value set to tid,levelValue.
The logging attributes are saved successfully for ManagedServer1-config.
Command set-log-attributes executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help set-log-attributes
at the command line.
To Disable Multiline Mode
Use the set-log-attributes
command in remote mode to disable the multiline mode.
When multiline mode is enabled (the default), the body of a log
message starts on a new line after the message header and is indented.
-
Ensure that the DAS is running. Remote commands require a running server.
-
Set multiline mode by using the
set-log-attributes
subcommand, specifying the formatter attribute and its value (true
orfalse
): -
To apply your change, restart the instance.
Example 7-11 Disabling the Multiline Mode in the log file
Multiline mode is enabled by default.
The following example disables multiline mode in log files
for standalone instance ManagedServer1
:
asadmin set-log-attributes --target ManagedServer1 \
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.multiline=false
org.glassfish.main.jul.handler.GlassFishLogHandler.formatter.multiline logging attribute value set to false.
The logging attributes are saved successfully for ManagedServer1-config.
Command set-log-attributes executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help set-log-attributes
at the command line.
Setting Log File Rotation
As explained in The Server Log File, Eclipse GlassFish by default rotates
the server.log
file when it’s size exceeds 100 MB.
However, you can change the default rotation settings.
For example, you can change the file size limit at which the server
rotates the log file or you can configure a server to rotate log files based
on a time interval.
In addition to changing when rotation occurs, you can also:
-
Specify the maximum number of rotated files that can accumulate. By default, Eclipse GlassFish does not limit the number of rotated log files that are retained. However, you can set a limit. After the number of log files reaches this limit, subsequent file rotations delete the oldest rotated log file.
-
Rotate the log file manually. A manual rotation forces the immediate rotation of the target log file.
Changing the default log rotation settings is done using the
set-log-attributes
subcommand, and rotating log files manually is done
using the rotate-log
subcommand, as explained in the following
sections:
To Change the Rotation File Size
Use the set-log-attributes
subcommand in remote mode to change the log
rotation file size.
The default target of this subcommand is the DAS.
Optionally, you can target a configuration, server, instance, or cluster.
-
Ensure that the DAS is running.
-
Change the rotation file size limit by using the
set-log-attributes
subcommand, specifying the attribute and the desired limit in megabytes:org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.megabytes=1000
-
Changes will be applied automatically after saving the change to the instance’s
logging.properties
file.
Example 7-12 Changing the Rotation Size
The following example sets the log file rotation size to 1 MB for the
standalone instance ManagedServer1
:
asadmin set-log-attributes --target ManagedServer1 \
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.megabytes=1000
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.megabytes logging attribute value set to 1000.
The logging attributes are saved successfully for ManagedServer1-config.
Command set-log-attributes executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help set-log-attributes
at the command line.
To Change the File Rotation Interval
Use the set-log-attributes
subcommand in remote mode to change the log
file rotation time limit interval.
The default target of this subcommand is the DAS.
Optionally, you can target a configuration, server, instance, or cluster.
The default value is 0
.
-
Ensure that the DAS is running.
-
Change the rotation time limit by using the
set-log-attributes
subcommand, specifying the following attribute and the desired limit in minutes:org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.minutes=minutes
-
Changes will be applied automatically after saving the change to the instance’s
logging.properties
file.
Example 7-13 Changing the Rotation Interval
The following example sets the log file rotation time limit for the
cluster Cluster1
, and all it’s instances.
asadmin set-log-attributes --target Cluster1 \
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.minutes=60
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.limit.minutes logging attribute value set to 60.
The logging attributes are saved successfully for cluster-config.
Command set-log-attributes executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help set-log-attributes
at the command line.
To Change the Limit Number of Archive Log Files
Use the set-log-attributes
subcommand in remote mode to change the limit
on the number of log files that the server creates to store old log messages.
The default target of this subcommand is the DAS.
Optionally, you can target a configuration, server, instance, or cluster.
The default limit value is 0
, which results in no limit placed on the number
of rotated log files that are retained.
-
Ensure that the DAS is running.
-
Change the limit number of retained log files by using the
set-log-attributes
subcommand, specifying the following attribute and the desired file limit number:org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.maxArchiveFiles=number
-
Changes will be applied automatically after saving the change to the instance’s effective
logging.properties
file.
Example 7-14 Changing the Limit Number of Archived Log Files
The following example sets the log limit number of retained log files
for the DAS to 10
.
asadmin set-log-attributes \
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.maxArchiveFiles=10
org.glassfish.main.jul.handler.GlassFishLogHandler.rotation.maxArchiveFiles logging attribute value set to 10.
The logging attributes are saved successfully for server.
Command set-log-attributes executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help set-log-attributes
at the command line.
To Rotate Log Files Manually
You can rotate log files manually by using the rotate-log
subcommand in remote mode.
The default target of this subcommand is the DAS.
Optionally, you can target a configuration, server, instance, or cluster.
When you use this subcommand, the target log file is immediately moved
to a new time-stamped file and a new log file is created.
Because log rotation is a dynamic operation, you do not need to restart Eclipse GlassFish for changes to take effect.
-
Ensure that the target server or cluster is running.
-
Rotate log files by using the
rotate-log
subcommand.
Example 7-15 Rotating Log Files Manually
The following example rotates the server.log
file for ManagedServer2
to server.log_yyyy-mm-dd`T`hh-mm-ss
, where yyyy-mm-dd`T`hh-mm-ss
represents the time when the file is rotated, and creates a new server.log
file.
asadmin rotate-log --target ManagedServer2
Rotated log on instance named 'ManagedServer2'.
Command rotate-log executed successfully.
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help rotate-log
at the command line.
Viewing Log Records
The recommended means for general viewing of logging information is to use the Log Viewer in the Administration Console. The Log Viewer simplifies reading, searching, and filtering log file contents. For instructions, see the Administration Console online help.
Eclipse GlassFish also allows you to collect log
files into a ZIP archive, which provides the means to obtain and view
log files for an instance or cluster even when it is not currently running.
The following section explains how to collect all available log
files for an instance or cluster and compile them into a single ZIP archive,
which is done by using the collect-log-files
subcommand.
To Collect Log Files into a ZIP Archive
Use the collect-log-files
subcommand in remote mode to collect log
files into a ZIP archive. The default target of this subcommand is the DAS.
Optionally you can target a configuration, server, instance, or cluster.
-
Ensure that the target server or cluster is running. Remote subcommands require a running server.
-
Use the
collect-log-files
subcommand to create the ZIP archive.The default location in which the ZIP archive is created is the domain-dir
/collected-logs
directory. Thecollect-log-files
subcommand allows you to specify a nondefault directory in which the ZIP archive is to be created by using the--retrieve
option set totrue
, followed by the directory name.The name of the ZIP file contains the timestamp, as follows:
log_yyyy-mm-dd_hh-min-sec.zip
Example 7-16 Collecting and Downloading Log Files as a ZIP File
This example shows collecting the log files for the cluster Cluster1
and compiling them into a ZIP archive in the /tmp/space/output
directory.
asadmin collect-log-files --target Cluster1 --retrieve true /tmp/space/output
Log files are downloaded for ClusterServer1.
Log files are downloaded for ClusterServer2.
Created Zip file under /tmp/space/output/log_2022-08-06_14-57-53.zip.
Command collect-log-files executed successfully.
When the ZIP file created by the preceding command is uncompressed, the following directory structure is created:
as-install-parent/
glassfish/
domains/
domain-dir/
collected_logs/
logs/
ClusterServer1/
server.log
ClusterServer2/
server.log
See Also
You can view the full syntax and options of the subcommand by typing
asadmin help collect-log-files
at the command line.
Listing Loggers
You can list and view information about all public loggers in your distribution of Eclipse GlassFish.
To List Loggers
Use the list-loggers
subcommand in remote mode to list the logger
name, subsystem, and description of subsystem loggers in your distribution of
Eclipse GlassFish. Class name based loggers are not listed.
-
Ensure that the DAS is running. Remote commands require a running server.
-
List loggers by using the
list-loggers
subcommand.
Example 7-17 Listing Loggers
This example lists the logger name, subsystem, and description for each logger. Some lines of output are omitted from this example for readability.
asadmin list-loggers
Logger Name Subsystem Logger Description
...
jakarta.enterprise.system.core CORE Core Kernel
jakarta.enterprise.system.core.ee AS-CORE Jakarta EE Core Kernel
jakarta.enterprise.system.core.security SECURITY Core Security
jakarta.enterprise.system.core.security.web SECURITY Core-ee Security Logger
jakarta.enterprise.system.jmx JMX JMX System Logger
jakarta.enterprise.system.security.ssl SECURITY - SSL Security - SSL
...
Command list-loggers executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-loggers
at the command line.
As an alternative you can take a look into the default-logging.properties
file
which should contain all useful basic loggers set to a default level. The same
cofiguration is distributed in the new domain1’s logging.properties
file, so
you can print all actual logger names and levels as we described in To List Logger Levels.
8 Administering the Monitoring Service
This chapter explains how to monitor the Eclipse GlassFish 7 components and services by using the asadmin
command-line
utility. Instructions for configuring JConsole to monitor Eclipse GlassFish resources are also provided.
The following topics are addressed here:
Instructions for monitoring by using the Administration Console are contained in the Administration Console online help.
For information on using REST interfaces for monitoring, see Using REST Interfaces to Administer Eclipse GlassFish.
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 Eclipse GlassFish, 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 Eclipse GlassFish, monitoring is exposed in a modular
way so that many client modules can access and display the monitoring
statistics. These clients include the Administration Console, the
asadmin
utility, AMX, and REST interfaces.
The following topics are addressed here:
How the Monitoring Tree Structure Works
A monitorable object is a component, subcomponent, or service that can be monitored. Eclipse GlassFish uses a tree structure to track monitorable objects. Because the tree is dynamic, the tree changes as Eclipse GlassFish 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.jvm
server.network
server.orb
server.resources
server.security
server.thread-pool
server.transaction-service
server.web
Each object is represented by a dotted name. Dotted names can also
address specific attributes in monitorable objects. For example, the
jvm
object has a memory
attribute with a statistic called
maxheapsize
. The following dotted name addresses the attribute:
server.jvm.memory.maxheapsize
Although an object is monitorable, it is not necessarily being actively monitored. For instructions on activating monitoring, see Configuring Monitoring.
Tree Structure of Monitorable Objects
Each monitorable object has a hierarchical tree structure. In the tree, a replaceable such as *statistics represents the name of the attribute that you can show statistics for.
The following node tree hierarchies are addressed here:
Applications Tree Hierarchy
The applications
tree contains the following nodes:
server.applications
|--- application1
| |--- ejb-module-1
| | |--- ejb1 *
| | |--- bean-cache (for entity/sfsb) *
| | |--- bean-pool (for slsb/mdb/entity) *
| | |--- bean-methods
| | |---method1 *
| | |---method2 *
| | |--- timers (for s1sb/entity/mdb) *
| |--- web-module-1
| | |--- virtual-server-1 *
| | |---servlet1 *
| | |---servlet2 *
|--- standalone-web-module-1
| | |----- virtual-server-2 *
| | |---servlet3 *
| | |---servlet4 *
| | |----- virtual-server-3 *
| | |---servlet3 *(same servlet on different vs)
| | |---servlet5 *
|--- standalone-ejb-module-1
| | |--- ejb2 *
| | |--- bean-cache (for entity/sfsb) *
| | |--- bean-pool (for slsb/mdb/entity) *
| | |--- bean-methods
| | |--- method1 *
| | |--- method2 *
| | |--- timers (for s1sb/entity/mdb) *
|--- jersey-application-1
| |--- jersey
| | |--- resources
resource-0
hitcount
*statistic
|--- application2
An example dotted name might be:
server.applications.hello.server.request.maxtime
An example dotted name under the EJB method
node might be:
server.applications.ejbsfapp1.ejbsfapp1ejbmod1\.jar.SFApp1EJB1
An example Jersey dotted name might be:
server.applications.helloworld-webapp.jersey.resources.resource-0.hitcount.resourcehitcount-count
For available statistics, see EJB Statistics, Jersey Statistics, and Web Statistics.
Connector Service Tree Hierarchy
The connector-service
tree holds monitorable attributes for pools such
as the connector connection pool. The connector-service
tree contains
the following nodes:
server.connector-service
resource-adapter-1
connection-pools
pool-1
work-management
An example dotted name might be
server.connector-service.resource-adapter-1.connection-pools.pool-1
.
For available statistics, see JMS/Connector Service Statistics.
HTTP Service Tree Hierarchy
The http-service
tree contains the following nodes:
server.http-service
virtual-server
request
*statistic
_asadmin
request
*statistic
An example dotted name under the virutal-server node might be
server.http-service.virtual-server1.request.requestcount
. For
available statistics, see HTTP Service Statistics.
JMS/Container Service Tree Hierarchy
The jms-service
tree holds monitorable attributes for connection
factories (connection pools for resource adapters) and work management
(for Message Queue resource adapters). The jms-service
tree contains
the following nodes:
server.jms-service
connection-factories
connection-factory-1
work-management
An example dotted name under the connection-factories
node might be
server.jms-service.connection-factories.connection-factory-1
which
shows all the statistics for this connection factory. For available
statistics, see JMS/Connector Service Statistics.
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 Eclipse GlassFish can gather at runtime. Adding monitoring capabilities enables an add-on component to provide statistics to Eclipse GlassFish in the same way as components that are supplied in the Eclipse GlassFish distributions. As a result, you can use the same administrative interfaces to monitor statistics from any installed Eclipse GlassFish component, regardless of the origin of the component.
Tools for Monitoring Eclipse GlassFish
The following asadmin
subcommands are provided for monitoring the
services and components of Eclipse GlassFish:
-
The
enable-monitoring
,disable-monitoring
, or theget
andset
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 themonitor
subcommand. For guidelines and instructions, see Guidelines for Using thelist
andget
Subcommands for Monitoring. -
The
get
subcommand is used to display comprehensive data, such as the attributes and values for a dotted name. Theget
subcommand used with a wildcard parameter displays all available attributes for any monitorable object. For additional information, see Guidelines for Using thelist
andget
Subcommands for Monitoring.
Configuring Monitoring
By default, the monitoring service is enabled for Eclipse GlassFish, but monitoring for the individual modules is not. To enable monitoring for a module, you change the monitoring level for that module to LOW or HIGH, You can choose to leave monitoring OFF for objects that do not need to be monitored.
-
LOW. Simple statistics, such as create count, byte count, and so on
-
HIGH. Simple statistics plus method statistics, such as method count, duration, and so on
-
OFF. No monitoring, no impact on performance
The following tasks are addressed here:
To Enable Monitoring
Use the enable-monitoring
subcommand to enable the monitoring service
itself, or to enable monitoring for individual modules. Monitoring is
immediately activated, without restarting Eclipse GlassFish.
You can also use the set
subcommand to enable
monitoring for a module. Using the set
command is not a dynamic
procedure, so you need to restart Eclipse GlassFish for your changes to
take effect.
-
Determine which services and components are currently enabled for monitoring.
asadmin> get server.monitoring-service.module-monitoring-levels.*
This example output shows that the HTTP service is not enabled (OFF for monitoring), but other objects are enabled:
configs.config.server-config.monitoring-service.module-monitoring-levels.web-container=HIGH configs.config.server-config.monitoring-service.module-monitoring-levels.http-service=OFF configs.config.server-config.monitoring-service.module-monitoring-levels.jvm=HIGH
-
Enable monitoring by using the
enable-monitoring
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 Eclipse GlassFish.
You can also use the set
subcommand to disable
monitoring for a module. Using the set
command is not a dynamic
procedure, so you need to restart Eclipse GlassFish for your changes to
take effect.
-
Determine which services and components currently are enabled for monitoring.
asadmin get server.monitoring-service.module-monitoring-levels.*
This example output shows that monitoring is enabled for
web-container
,http-service
, andjvm
:configs.config.server-config.monitoring-service.module-monitoring-levels.web-container=HIGH configs.config.server-config.monitoring-service.module-monitoring-levels.http-service=HIGH configs.config.server-config.monitoring-service.module-monitoring-levels.jvm=HIGH
-
Disable monitoring for a service or module by using the
disable-monitoring
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
Use the --type
option of the monitor
subcommand to specify the
object for which you want to display data, such as httplistener
,
jvm
, webmodule
. If you use the monitor
subcommand without
specifying a type, an error message is displayed.
Output from the subcommand is displayed continuously in a tabular
format. The --interval
option can be used to display output at a
particular interval (the default is 30 seconds).
Before You Begin
A monitorable object must be configured for monitoring before you can display data on the object. See To Enable Monitoring.
-
Determine which type of monitorable object you want to monitor.
Your choices for 5.0 are
jvm
,httplistener
, andwebmodule
. -
Request the monitoring data by using the
monitor
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
The statistics available for the httplistener
type are shown in the following table.
Table 8-1 HTTP Listener Common Monitoring Statistics
Statistic | Description |
---|---|
|
Error count. Cumulative value of the error count |
|
Maximum time. Longest response time for a request; not a cumulative value, but the largest response time from among the response times |
|
Processing time. Cumulative value of the times taken to process each request, with processing time being the average of request processing times over request |
|
Request count. Cumulative number of requests processed so far |
JVM Common Statistics
The statistics available for the jvm
type are shown in the following table.
Table 8-2 JVM Common Monitoring Statistics
Statistic | Description |
---|---|
|
Amount of memory (in bytes) that is guaranteed to be available for use by the JVM machine |
|
Retained for compatibility with other releases |
|
Retained for compatibility with other releases |
|
The maximum amount of memory that can be used for memory management. |
|
Initial amount of memory (in bytes) that the JVM machine requests from the operating system for memory management during startup |
|
Number of milliseconds that the JVM machine has been running since it was last started |
Web Module Common Statistics
The statistics available for the webmodule
type are shown in the
following table.
Table 8-3 Web Module Common Monitoring Statistics
Statistic | Description |
---|---|
|
Number of active JavaServer Pages (JSP) technology pages that are loaded |
|
Current active sessions |
|
Number of active servlets that are loaded |
|
Total active sessions |
|
Maximum number of JSP pages that are loaded |
|
Maximum number of servlets that are loaded |
|
Total rejected sessions |
|
Total sessions |
|
Total number of JSP pages that are loaded |
|
Total number of servlets that are loaded |
Viewing Comprehensive Monitoring Data
By applying the list
and get
subcommands against the tree structure
using dotted names, you can display more comprehensive monitoring data,
such as a description of each of the statistics and its unit of
measurement.
The following topics are addressed here:
Guidelines for Using the list
and get
Subcommands for Monitoring
The underlying assumptions for using the list
and get
subcommands
with dotted names are:
-
A
list
subcommand that specifies a dotted name that is not followed by a wildcard (*
) lists the current node’s immediate children. For example, the following subcommand lists all immediate children belonging to theserver
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 theapplications
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 agets the set of attributes and their values that belong to the node specified.
For example, the following table explains the output of the list
and
get
subcommands used with the dotted name for the resources
node.
Table 8-4 Example Resources Level Dotted Names
Subcommand | Dotted Name | Output |
---|---|---|
|
|
List of pool names. |
|
|
No attributes,
but a message saying "Use |
|
|
List of attributes and values corresponding to connection pool attributes. |
For detailed information on dotted names, see the
dotted-names
(5ASC) help page.
To View Comprehensive Monitoring Data
Although the monitor
subcommand is useful in many situations, it does
not offer the complete list of all monitorable objects. To work with
comprehensive data for an object type, use the list
monitor
and the
get
monitor
subcommands followed by the dotted name of a monitorable
object.
Before You Begin
A monitorable object must be configured for monitoring before you can display information about the object. See To Enable Monitoring if needed.
-
List the objects that are enabled for monitoring by using the
list
subcommand.For example, the following subcommand lists all components and services that have monitoring enabled for instance
server
.asadmin> list --monitor "*" server.web server.connector-service server.orb server.jms-serviceserver.jvm server.applications server.http-service server.thread-pools
-
Get data for a monitored component or service by using the
get
subcommand.
Example 8-8 Viewing Attributes for a Specific Type
This example gets information about all the attributes for object type
jvm
on instance server
.
asadmin> get --monitor server.jvm.*
server.jvm.class-loading-system.loadedclasscount = 3715
server.jvm.class-loading-system.totalloadedclasscount = 3731
server.jvm.class-loading-system.unloadedclasscount = 16
server.jvm.compilation-system.name-current = HotSpot Client Compiler
server.jvm.compilation-system.totalcompilationtime = 769
server.jvm.garbage-collectors.Copy.collectioncount = 285
server.jvm.garbage-collectors.Copy.collectiontime = 980
server.jvm.garbage-collectors.MarkSweepCompact.collectioncount = 2
server.jvm.garbage-collectors.MarkSweepCompact.collectiontime = 383
server.jvm.memory.committedheapsize = 23498752
server.jvm.memory.committednonheapsize = 13598720
server.jvm.memory.initheapsize = 0
server.jvm.memory.initnonheapsize = 8585216
server.jvm.memory.maxheapsize = 66650112
server.jvm.memory.maxnonheapsize = 100663296
server.jvm.memory.objectpendingfinalizationcount = 0
server.jvm.memory.usedheapsize = 19741184
server.jvm.memory.usednonheapsize = 13398352
server.jvm.operating-system.arch-current = x86
server.jvm.operating-system.availableprocessors = 2
server.jvm.operating-system.name-current = Windows XP
server.jvm.operating-system.version-current = 5.1
server.jvm.runtime.classpath-current = glassfish.jar
server.jvm.runtime.inputarguments-current = []
server.jvm.runtime.managementspecversion-current = 1.0
server.jvm.runtime.name-current = 4372@ABBAGANI_WORK
server.jvm.runtime.specname-current = Java Virtual Machine Specification
server.jvm.runtime.specvendor-current = Sun Microsystems Inc.
server.jvm.runtime.specversion-current = 1.0
server.jvm.runtime.uptime = 84813
server.jvm.runtime.vmname-current = Java HotSpot(TM) Client VM
server.jvm.runtime.vmvendor-current = Sun Microsystems Inc.
server.jvm.runtime.vmversion-current = 1.5.0_11-b03
Example 8-9 Viewing Monitorable Applications
This example lists all the monitorable applications for instance
server
.
asadmin> list --monitor server.applications.*
server.applications.app1
server.applications.app2
server.applications.app1.virtual-server1
server.applications.app2.virtual-server1
Example 8-10 Viewing Attributes for an Application
This example gets information about all the attributes for application
hello
.
asadmin> get --monitor server.applications.hello.*
server.applications.hello.server.activatedsessionstotal = 0
server.applications.hello.server.activejspsloadedcount = 1
server.applications.hello.server.activeservletsloadedcount = 1
server.applications.hello.server.activesessionscurrent = 1
server.applications.hello.server.activesessionshigh = 1
server.applications.hello.server.errorcount = 0
server.applications.hello.server.expiredsessionstotal = 0
server.applications.hello.server.maxjspsloadedcount = 1
server.applications.hello.server.maxservletsloadedcount = 0
server.applications.hello.server.maxtime = 0
server.applications.hello.server.passivatedsessionstotal = 0
server.applications.hello.server.persistedsessionstotal = 0
server.applications.hello.server.processingtime = 0.0
server.applications.hello.server.rejectedsessionstotal = 0
server.applications.hello.server.requestcount = 0
server.applications.hello.server.sessionstotal =
server.applications.hello.server.totaljspsloadedcount = 0
server.applications.hello.server.totalservletsloadedcount = 0
Example 8-11 Viewing a Specific Attribute
This example gets information about the jvm
attribute
runtime.vmversion-current
on instance server
.
asadmin> get --monitor server.jvm.runtime.vmversion-current
server.jvm.runtime.vmversion-current = 10.0-b23
Comprehensive Monitoring Statistics
You can get comprehensive monitoring statistics by forming a dotted name
that specifies the statistic you are looking for. For example, the
following dotted name will display the cumulative number of requests for
the HTTP service on virtual-server1
:
server.http-service.virtual-server1.request.requestcount
The tables in the following sections list the statistics that are available for each monitorable object:
EJB Statistics
EJBs fit into the tree of objects as shown in Applications Tree Hierarchy. Use the following dotted name pattern to get EJB statistics for an application:
server.applications.appname.ejbmodulename.ejbname.bean-cache.statistic
EJB statistics for an application are available after the application is executed. If the application is deployed but has not yet been executed, all counts will show default values. When the application is undeployed, all its monitoring data is lost. |
Statistics available for applications are shown in the following sections:
EJB Cache Statistics
Use the following dotted name pattern for EJB cache statistics:
server.applications.appname.ejbmodulename.bean-cache.ejbname.statistic
The statistics available for EJB caches are listed in the following table.
Table 8-5 EJB Cache Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
RangeStatistic |
The number of times a user request does not find a bean in the cache. |
|
RangeStatistic |
The number of times a user request found an entry in the cache. |
|
RangeStatistic |
The number of beans in the cache. This is the current size of the cache. |
|
CountStatistic |
Number of passivated beans. Applies only to stateful session beans. |
|
CountStatistic |
Number of errors during passivation. Applies only to stateful session beans. |
|
CountStatistic |
Number of expired sessions removed by the cleanup thread. Applies only to stateful session beans. |
|
CountStatistic |
Number of times passivation completed successfully. Applies only to stateful session beans. |
EJB Container Statistics
Use the following dotted name pattern for EJB container statistics:
server.applications.appname.ejbmodulename.container.ejbname
The statistics available for EJB containers are listed in the following table.
Table 8-6 EJB Container Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of times an EJB’s |
|
CountStatistic |
Number of messages received for a message-driven bean. |
|
RangeStatistic |
Number of stateful or stateless
session beans that are in the |
|
RangeStatistic |
Number of stateful session beans that
are in |
|
RangeStatistic |
Number of entity beans in pooled state. |
|
RangeStatistic |
Number of entity beans in ready state. |
|
CountStatistic |
Number of times an EJB’s |
EJB Method Statistics
Use the following dotted name pattern for EJB method statistics:
server.applications.appname.ejbmodulename.bean-methods.ejbname.statistic
The statistics available for EJB method invocations are listed in the following table.
Table 8-7 EJB Method Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Time, in milliseconds, spent executing the method for the last successful/unsuccessful attempt to run the operation. This is collected for stateless and stateful session beans and entity beans if monitoring is enabled on the EJB container. |
|
TimeStatistic |
Number of times an operation is called; the total time that is spent during the invocation, and so on. |
|
CountStatistic |
Number of times the method execution resulted in an exception. This is collected for stateless and stateful session beans and entity beans if monitoring is enabled for the EJB container. |
|
CountStatistic |
Number of times the method successfully executed. This is collected for stateless and stateful session beans and entity beans if monitoring enabled is true for EJB container. |
EJB Pool Statistics
Use the following dotted name pattern for EJB pool statistics:
server.applications.appname.ejbmodulename.bean-pool.ejbname.statistic
The statistics available for EJB pools are listed in the following table.
Table 8-8 EJB Pool Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
The maximum number of messages to load into a JMS session at one time for a message-driven bean to serve. Default is 1. Applies only to pools for message driven beans. |
|
RangeStatistic |
Number of EJBs in the associated pool, providing information about how the pool is changing. |
|
RangeStatistic |
Number of threads waiting for free beans, giving an indication of possible congestion of requests. |
|
CountStatistic |
Number of beans created in associated pool since the gathering of data started. |
|
CountStatistic |
Number of beans destroyed from associated pool since the gathering of data started. |
Timer Statistics
Use the following dotted name pattern for timer statistics:
server.applications.appname.ejbmodulename.timers.ejbname.statistic
The statistics available for timers are listed in the following table.
Table 8-9 Timer Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of timers created in the system. |
|
CountStatistic |
Number of timers delivered by the system. |
|
CountStatistic |
Number of timers removed from the system. |
HTTP Service Statistics
The HTTP service fits into the tree of objects as shown in HTTP Service Tree Hierarchy.
HTTP Service Virtual Server Statistics
Use the following dotted name pattern for HTTP service virtual server statistics:
server.http-service.virtual-server.request.statistic
The HTTP service statistics for virtual servers are shown in the following table.
Table 8-10 HTTP Service Virtual Server Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of responses with a status code equal to 200 |
|
CountStatistic |
Number of responses with a status code in the 2xx range |
|
CountStatistic |
Number of responses with a status code equal to 302 |
|
CountStatistic |
Number of responses with a status code equal to 304 |
|
CountStatistic |
Number of responses with a status code equal in the 3xx range |
|
CountStatistic |
Number of responses with a status code equal to 400 |
|
CountStatistic |
Number of responses with a status code equal to 401 |
|
CountStatistic |
Number of responses with a status code equal to 403 |
|
CountStatistic |
Number of responses with a status code equal to 404 |
|
CountStatistic |
Number of responses with a status code equal in the 4xx range |
|
CountStatistic |
Number of responses with a status code equal to 503 |
|
CountStatistic |
Number of responses with a status code equal in the 5xx range |
|
CountStatistic |
Number of responses with a status code outside the 2xx, 3xx, 4xx, and 5xx range |
|
CountStatistic |
Cumulative value of the error count, with error count representing the number of cases where the response code was greater than or equal to 400 |
|
StringStatistic |
The host (alias) names of the virtual server |
|
CountStatistic |
Longest response time for a request; not a cumulative value, but the largest response time from among the response times |
|
CountStatistic |
Cumulative value of the times taken to process each request, with processing time being the average of request processing times over the request count |
|
CountStatistic |
Cumulative number of requests processed so far |
|
StringStatistic |
The state of the virtual server |
Jersey Statistics
Jersey fits into the tree of objects as shown in Applications Tree Hierarchy.
Use the following dotted name pattern for Jersey statistics:
server.applications.jersey-application.jersey.resources.resource-0.hitcount.statistic
The statistics available for Jersey are shown in the following table.
Table 8-11 Jersey Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of hits on this resource class |
|
CountStatistic |
Number of hits on this root resource class |
JMS/Connector Service Statistics
The JMS/Connector Service fits into the tree of objects as shown in JMS/Container Service Tree Hierarchy.
JMS/Connector Service statistics are shown in the following sections:
Connector Connection Pool Statistics (JMS)
Use the following dotted name pattern for JMS/Connector Service connection pool statistics:
server.connector-service.resource-adapter-1.connection-pool.statistic
JMS/Connector Service statistics available for the connector connection pools are shown in the following table.
In order to improve system performance, connection pools are initialized lazily; that is, a pool is not initialized until an application first uses the pool or the pool is explicitly pinged. Monitoring statistics for a connection pool are not available until the pool is initialized. |
Table 8-12 Connector Connection Pool Monitoring Statistics (JMS)
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Average wait time of connections before they are serviced by the connection pool. |
|
RangeStatistic |
The longest and shortest wait times of connection requests. The current value indicates the wait time of the last request that was serviced by the pool. |
|
CountStatistic |
Total number of connections in the connection pool that failed validation from the start time until the last sample time. |
|
RangeStatistic |
Total number of connections that are currently being used, as well as information about the maximum number of connections that were used (the high water mark). |
|
RangeStatistic |
Total number of free connections in the pool as of the last sampling. |
|
CountStatistic |
Total number of connections in the pool that timed out between the start time and the last sample time. |
|
CountStatistic |
Number of physical connections, in milliseconds, that were created since the last reset. |
|
CountStatistic |
Number of physical connections that were destroyed since the last reset. |
|
CountStatistic |
Number of logical connections acquired from the pool. |
|
CountStatistic |
Number of logical connections released to the pool. |
|
CountStatistic |
Number of connection requests in the queue waiting to be serviced. |
Connector Work Management Statistics (JMS)
Use the following dotted name pattern for JMS/Connector Service work management statistics:
server.connector-service.resource-adapter-1.work-management.statistic
JMS/Connector Service statistics available for connector work management are listed in the following table.
Table 8-13 Connector Work Management Monitoring Statistics (JMS)
Statistic | Data Type | Description |
---|---|---|
|
RangeStatistic |
Number of work objects executed by the connector. |
|
CountStatistic |
Number of work objects that were completed. |
|
CountStatistic |
Number of work objects rejected by the Eclipse GlassFish. |
|
CountStatistic |
Number of work objects submitted by a connector module. |
|
RangeStatistic |
Number of work objects waiting in the queue before executing. |
|
RangeStatistic |
Longest and shortest wait of a work object before it gets executed. |
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
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://docs.oracle.com/javase/8/docs/technotes/tools/
.
The statistics that are available for class loading in the JVM for Java SE are shown in the following table.
Table 8-14 JVM Monitoring Statistics for Java SE Class Loading
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of classes that are currently loaded in the JVM |
|
CountStatistic |
Total number of classes that have been loaded since the JVM began execution |
|
CountStatistic |
Number of classes that have been unloaded from the JVM since the JVM began execution |
The statistics available for threads in the JVM in Java SE are shown in the following table.
Table 8-15 JVM Monitoring Statistics for Java SE - Threads
Statistic | Data Type | Description |
---|---|---|
|
StringStatistic |
List of all live thread ids. |
|
CountStatistic |
CPU time for the current thread (in nanoseconds) if CPU time measurement is enabled. If CPU time measurement is disabled, returns -1. |
|
CountStatistic |
Current number of live daemon threads. |
|
StringStatistic |
List of thread ids that are monitor deadlocked. |
|
CountStatistic |
Peak live thread count since the JVM started or the peak was reset. |
|
CountStatistic |
Current number of live daemon and non-daemon threads. |
|
CountStatistic |
Total number of threads created and/or started since the JVM started. |
JVM Compilation System Statistics
Use the following dotted name pattern for JVM compilation system statistics:
server.jvm.compilation-system.statistic
The statistics that are available for compilation in the JVM for Java SE are shown in the following table.
Table 8-16 JVM Monitoring Statistics for Java SE Compilation
Statistic | Data Type | Description |
---|---|---|
|
StringStatistic |
Name of the current compiler |
|
CountStatistic |
Accumulated time (in milliseconds) spent in compilation |
JVM Garbage Collectors Statistics
Use the following dotted name pattern for JVM garbage collectors statistics:
server.jvm.garbage-collectors.statistic
The statistics that are available for garbage collection in the JVM for Java SE are shown in the following table.
Table 8-17 JVM Monitoring Statistics for Java SE Garbage Collectors
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Total number of collections that have occurred |
|
CountStatistic |
Accumulated time (in milliseconds) spent in collection |
JVM Memory Statistics
Use the following dotted name pattern for JVM memory statistics:
server.jvm.memory.statistic
The statistics that are available for memory in the JVM for Java SE are shown in the following table.
Table 8-18 JVM Monitoring Statistics for Java SE Memory
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Amount of heap memory (in bytes) that is committed for the JVM to use |
|
CountStatistic |
Amount of non-heap memory (in bytes) that is committed for the JVM to use |
|
CountStatistic |
Size of the heap initially requested by the JVM |
|
CountStatistic |
Size of the non-heap area initially requested by the JVM |
|
CountStatistic |
Maximum amount of heap memory (in bytes) that can be used for memory management |
|
CountStatistic |
Maximum amount of non-heap memory (in bytes) that can be used for memory management |
|
CountStatistic |
Approximate number of objects that are pending finalization |
|
CountStatistic |
Size of the heap currently in use |
|
CountStatistic |
Size of the non-heap area currently in use |
JVM Operating System Statistics
Use the following dotted name pattern for JVM operating system statistics:
server.jvm.operating-system.statistic
The statistics that are available for the operating system for the JVM machine in Java SE are shown in the following table.
Table 8-19 JVM Statistics for the Java SE Operating System
Statistic | Data Type | Description |
---|---|---|
|
StringStatistic |
Operating system architecture |
|
CountStatistic |
Number of processors available to the JVM |
|
StringStatistic |
Operating system name |
|
StringStatistic |
Operating system version |
JVM Runtime Statistics
Use the following dotted name pattern for JVM runtime statistics:
server.jvm.runtime.statistic
The statistics that are available for the runtime in the JVM runtime for Java SE are shown in the following table.
Table 8-20 JVM Monitoring Statistics for Java SE Runtime
Statistic | Data Type | Description |
---|---|---|
|
StringStatistic |
Classpath that is used by the system class loader to search for class files |
|
StringStatistic |
Input arguments passed to
the JVM; not including arguments to the |
|
StringStatistic |
Management specification version implemented by the JVM |
|
StringStatistic |
Name representing the running JVM |
|
StringStatistic |
JVM specification name |
|
StringStatistic |
JVM specification vendor |
|
StringStatistic |
JVM specification version |
|
CountStatistic |
Uptime of the JVM (in milliseconds) |
|
StringStatistic |
JVM implementation name |
|
StringStatistic |
JVM implementation vendor |
|
StringStatistic |
JVM implementation version |
Network Statistics
Network fits into the tree of objects as shown in Network Tree Hierarchy.
Network statistics are described in the following sections:
Network Keep Alive Statistics
Use the following dotted name pattern for network keep alive statistics:
server.network.type-of-listener.keep-alive.statistic
Statistics available for network keep alive are shown in the following table.
Table 8-21 Network Keep Alive Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of connections in keep-alive mode. |
|
CountStatistic |
Number of keep-alive connections that timed out. |
|
CountStatistic |
Keep-alive timeout value in seconds. |
|
CountStatistic |
Maximum number of requests allowed on a single keep-alive connection. |
|
CountStatistic |
Number of keep-alive connections that were closed. |
|
CountStatistic |
Number of requests received by connections in keep-alive mode. |
|
CountStatistic |
Number of keep-alive connections that were rejected. |
Network Connection Queue Statistics
Use the following dotted name pattern for network connection queue statistics:
server.network.type-of-listener.connection-queue.statistic
Statistics available for network connection queue are shown in the following table.
Table 8-22 Network Connection Queue Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
The number of open/active connections |
|
CountStatistic |
Number of times the queue has been too full to accommodate a connection |
|
CountStatistic |
Number of connections currently in the queue |
|
CountStatistic |
Average number of connections queued in the last 15 minutes |
|
CountStatistic |
Average number of connections queued in the last 1 minute |
|
CountStatistic |
Average number of connections queued in the last 5 minutes |
|
CountStatistic |
Total number of connections that have been accepted |
|
CountStatistic |
Total number of connections that have been queued |
|
CountStatistic |
Maximum size of the connection queue |
|
CountStatistic |
Largest number of connections that were in the queue simultaneously |
|
CountStatistic |
(Unsupported) Total number of ticks that connections have spent in the queue |
Network File Cache Statistics
Use the following dotted name pattern for network file cache statistics:
server.network.type-of-listener.file-cache.statistic
Statistics available for network file cache are shown in the following table.
Table 8-23 Network File Cache Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of hits on cached file content |
|
CountStatistic |
Number of misses on cached file content |
|
CountStatistic |
Current cache size in bytes |
|
CountStatistic |
Number of cache lookup hits |
|
CountStatistic |
Number of hits on cached file info |
|
CountStatistic |
Number of misses on cached file info |
|
CountStatistic |
Size of mapped memory used for caching in bytes |
|
CountStatistic |
Maximum heap space used for cache in bytes |
|
CountStatistic |
Maximum memory map size used for caching in bytes |
|
CountStatistic |
Number of cache lookup misses data type |
|
CountStatistic |
Number of current open cache entries |
Network Thread Pool Statistics
Use the following dotted name pattern for network thread pool statistics:
server.network.type-of-listener.thread-pool.statistic
Statistics available for network thread pool are shown in the following table.
Table 8-24 Network Thread Pool Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Core number of threads in the thread pool |
|
CountStatistic |
Provides the number of request processing threads currently in the listener thread pool |
|
CountStatistic |
Provides the number of request processing threads currently in use in the listener thread pool serving requests |
|
CountStatistic |
Maximum number of threads allowed in the thread pool |
|
CountStatistic |
Provides the total number of tasks, which were executed by the thread pool |
ORB Statistics (Connection Manager)
The ORB fits into the tree of objects as shown in ORB Tree Hierarchy.
Use the following dotted name patterns for ORB statistics:
server.orb.transport.connectioncache.inbound.statistic
server.orb.transport.connectioncache.outbound.statistic
The statistics available for the connection manager in an ORB are listed in the following table.
Table 8-25 ORB Monitoring Statistics (Connection Manager)
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Total number of connections that are idle to the ORB |
|
CountStatistic |
Total number of connections in use to the ORB |
|
BoundedRangeStatistic |
Total number of connections to the ORB |
Resource Statistics (Connection Pool)
By monitoring connection pool resources you can measure performance and capture resource usage at runtime. Connections are expensive and frequently cause performance bottlenecks in applications. It is important to monitor how a connection pool is releasing and creating new connections and how many threads are waiting to retrieve a connection from a particular pool.
The connection pool resources fit into the tree of objects as shown in Resources Tree Hierarchy.
Use the following dotted name pattern for general connection pool statistics:
server.resources.pool-name.statistic
Use the following dotted name pattern for application-scoped connection pool statistics:
server.applications.application-name.resources.pool-name.statistic
Use the following dotted name pattern for module-scoped connection pool statistics:
server.applications.application-name.module-name.resources.pool-name.statistic
The connection pool statistics are shown in the following tables.
In order to improve system performance, connection pools are initialized lazily; that is, a pool is not initialized until an application first uses the pool or the pool is explicitly pinged. Monitoring statistics for a connection pool are not available until the pool is initialized. |
Table 8-26 General Resource Monitoring Statistics (Connection Pool)
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Average wait-time-duration per successful connection request |
|
RangeStatistic |
Longest and shortest wait times, in milliseconds, of connection requests since the last sampling. current value indicates the wait time of the last request that was serviced by the pool |
|
CountStatistic |
Number of logical connections acquired from the pool since the last sampling |
|
CountStatistic |
Number of physical connections that were created by the pool since the last reset |
|
CountStatistic |
Number of physical connections that were destroyed since the last reset |
|
CountStatistic |
Number of connections in the connection pool that failed validation from the start time until the last sampling time |
|
RangeStatistic |
Number of free connections in the pool as of the last sampling |
|
CountStatistic |
Number of connections rejected during matching |
|
CountStatistic |
Number of connections released back to the pool since the last sampling |
|
CountStatistic |
Number of connections successfully matched |
|
CountStatistic |
Number of connections in the pool that timed out between the start time and the last sampling time |
|
RangeStatistic |
Number of connections that are currently being used, as well as information about the maximum number of connections that were used (high water mark) |
|
StringStatistic |
List of the most frequently used SQL queries (Available only when SQL Tracing is enabled) |
|
CountStatistic |
Number of potential connection leaks |
|
CountStatistic |
Number of potential statement leaks (Available only when Statement Leak Dectection is enabled) |
|
CountStatistic |
Number of statements that were found in the statement cache (Available only when the Statement Cache is enabled) |
|
CountStatistic |
Number of statements that were not found in the statement cache (Available only when the Statement Cache is enabled) |
|
CountStatistic |
Number of connection requests in the queue waiting to be serviced |
Table 8-27 Application Specific Resource Monitoring Statistics (Connection Pool)
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of logical connections acquired from the pool since the last sampling |
|
CountStatistic |
Number of connections released back to the pool since the last sampling |
|
RangeStatistic |
Number of connections that are currently being used, as well as information about the maximum number of connections that were used (high water mark) |
Security Statistics
Security fits into the tree of objects as shown in Security Tree Hierarchy.
Statistics available for security are shown in the following sections:
EJB Security Statistics
Use the following dotted name pattern for EJB security statistics:
server.security.ejb.statistic
The statistics available for EJB security are listed in the following table.
Table 8-28 EJB Security Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of policy configuration |
|
CountStatistic |
Number of EJB security managers |
Web Security Statistics
Use the following dotted name pattern for web security statistics:
server.security.web.statistic
The statistics available for web security are listed in the following table.
Table 8-29 Web Security Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of security managers |
|
CountStatistic |
Number of policy configuration objects |
Realm Security Statistics
Use the following dotted name pattern for realm security statistics:
server.security.realm.statistic
The statistics available for realm security are listed in the following table.
Table 8-30 Realm Security Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of realms |
Thread Pool Statistics
The thread pool fits into the tree of objects as shown in Thread Pool Tree Hierarchy.
The statistics available for thread pools are shown in the following sections:
Thread Pool Monitoring Statistics
Use the following dotted name pattern for thread pool statistics:
server.thread-pool.thread-pool.statistic
The statistics available for the thread pool are shown in the following table.
Table 8-31 Thread Pool Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
BoundedRangeStatistic |
Average amount of time (in milliseconds) a request waited in the queue before being processed |
|
BoundedRangeStatistic |
Average amount of time (in milliseconds) taken to complete an assignment |
|
CountStatistic |
Number of busy threads |
|
BoundedRangeStatistic |
Current number of request processing threads |
|
CountStatistic |
Number of available threads |
|
BoundedRangeStatistic |
Current number of work items waiting in queue |
|
CountStatistic |
Total number of work items added to the work queue as of last sampling |
JVM Statistics for Java SE - Thread Information
The statistics available for ThreadInfo
in the JVM in Java SE are
shown in the following table.
Table 8-32 JVM Monitoring Statistics for Java SE - Thread Info
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Total number of times that the thread
entered the |
|
CountStatistic |
Time elapsed (in milliseconds) since the
thread entered the |
|
StringStatistic |
String representation of the monitor lock
that the thread is blocked to enter or waiting to be notified through
the |
|
CountStatistic |
ID of the thread that holds the monitor lock of an object on which this thread is blocking. |
|
StringStatistic |
Name of the thread that holds the monitor lock of the object this thread is blocking on. |
|
StringStatistic |
Stack trace associated with this thread. |
|
CountStatistic |
ID of the thread. |
|
StringStatistic |
Name of the thread. |
|
StringStatistic |
State of the thread. |
|
CountStatistic |
Elapsed time (in milliseconds) that the
thread has been in a |
|
CountStatistic |
Total number of times the thread was in
|
Transaction Service Statistics
The transaction service allows the client to freeze the transaction subsystem in order to roll back transactions and determine which transactions are in process at the time of the freeze. The transaction service fits into the tree of objects as shown in Transactions Service Tree Hierarchy.
Use the following dotted name pattern for transaction service statistics:
server.transaction-service.statistic
The statistics available for the transaction service are shown in the following table.
Table 8-33 Transaction Service Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Number of transactions currently active. |
|
StringStatistic |
The ID’s of the transactions that are currently active. Every such transaction can be rolled back after freezing the transaction service. |
|
CountStatistic |
Number of transactions that have been committed. |
|
CountStatistic |
Number of transactions that have been rolled back. |
|
StringStatistic |
Indicates whether or not the transaction has been frozen. |
Web Statistics
The web module fits into the tree of objects as shown in Web Tree Hierarchy.
The available web statistics shown in the following sections:
Web Module Servlet Statistics
Use the following dotted name pattern for web module servlet statistics:
server.applications.web-module.virtual-server.servlet.statistic
server.applications.application.web-module.virtual-server.servlet.statistic
The available web module servlet statistics are shown in the following table.
Table 8-34 Web Module Servlet Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Cumulative number of cases where the response code is greater than or equal to 400. |
|
CountStatistic |
Maximum amount of time the web container waits for requests. |
|
CountStatistic |
Cumulative value of the amount of time required to process each request. The processing time is the average of request processing times divided by the request count. |
|
CountStatistic |
The total number of requests processed so far. |
|
CountStatistic |
Aggregate response time in milliseconds. |
Web JSP Statistics
Use the following dotted name pattern for web JSP statistics:
server.applications.web-module.virtual-server.statistic
server.applications.application.web-module.virtual-server.statistic
The available web JSP statistics are shown in the following table.
Table 8-35 Web JSP Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
RangeStatistic |
Number of active JSP pages |
|
CountStatistic |
Total number of errors triggered by JSP page invocations |
|
CountStatistic |
Total number of JSP pages that were reloaded |
|
CountStatistic |
Total number of JSP pages ever loaded |
Web Request Statistics
Use the following dotted name pattern for web request statistics:
server.applications.web-module.virtual-server.statistic
server.applications.application.web-module.virtual-server.statistic
The available web request statistics are shown in the following table.
Table 8-36 Web Request Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Cumulative value of the error count, with error count representing the number of cases where the response code was greater than or equal to 400 |
|
CountStatistic |
Longest response time for a request; not a cumulative value, but the largest response time from among the response times |
|
CountStatistic |
Average request processing time, in milliseconds |
|
CountStatistic |
Cumulative number of the requests processed so far |
Web Servlet Statistics
Use the following dotted name pattern for web servlet statistics:
server.applications.web-module.virtual-server.statistic
server.applications.application.web-module.virtual-server.statistic
The available web servlet statistics are shown in the following table.
Table 8-37 Web Servlet Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
RangeStatistic |
Number of currently loaded servlets |
|
CountStatistic |
Cumulative servlet processing times , in milliseconds |
|
CountStatistic |
Cumulative number of servlets that have been loaded into the web module |
Web Session Statistics
Use the following dotted name pattern for web session statistics:
server.applications.web-module.virtual-server.statistic
server.applications.application.web-module.virtual-server.statistic
The available web session statistics are shown in the following table.
Table 8-38 Web Session Monitoring Statistics
Statistic | Data Type | Description |
---|---|---|
|
CountStatistic |
Total number of activated sessions |
|
RangeStatistic |
Number of currently active sessions |
|
CountStatistic |
Maximum number of concurrently active sessions |
|
CountStatistic |
Total number of expired sessions |
|
CountStatistic |
Total number of passivated sessions |
|
CountStatistic |
Total number of persisted sessions |
|
CountStatistic |
Total number of rejected sessions |
|
CountStatistic |
Total number of sessions created |
Configuring JConsole to View Eclipse GlassFish Monitoring Data
Java SE provides tools to connect to an MBean Server and view the MBeans registered with the server. JConsole is one such popular JMX Connector Client and is available as part of the standard Java SE distribution. When you configure JConsole for use with Eclipse GlassFish, Eclipse GlassFish becomes the JMX Connector’s server end and JConsole becomes the JMX connector’s client end.
To Connect JConsole to Eclipse GlassFish
Java SE 6 enhanced management and monitoring of the virtual machine by including a Platform MBean Server and by including managed beans (MBeans) to configure the virtual machine.
To view all MBeans, Eclipse GlassFish provides a configuration of the standard JMX connector server called System JMX Connector Server. As part of Eclipse GlassFish startup, an instance of this JMX Connector Server is started. Any compliant JMX connector client can connect to the server using the JMX Connector Server.
By default, Eclipse GlassFish is configured with a non-secure System JMX
Connector Server. If this is an issue, the JMX connector can be removed.
However, access can be restricted to a specific IP address (for example,
the loopback address) by setting address
to locahost
.
-
Start the domain.
For instructions, see To Start a Domain.
-
Start JConsole using this format: JDK_HOME
/bin/jconsole
For example:
/usr/java/bin/jconsole
The JConsole Connect to Agent window is displayed.
-
Click the Remote tab and type the host name and port.
Always connect remotely with JConsole, otherwise MBeans will not load automatically.
-
Click Connect.
-
In the Remote Process text box, specify the JMX Service URL.
For example:
service:jmx:rmi:///jndi/rmi://localhost:8686/jmxrmi
The JMX Service URL is emitted by the server at startup, looking something like this:
[#|2009-12-03T10:25:17.737-0800|INFO|glassfish7.0| x..system.tools.admin.org.glassfish.server|_ThreadID=20; _ThreadName=Thread-26;|JMXStartupService: Started JMXConnector, JMXService URL = service:jmx:rmi://localhost:8686/jndi/rmi://localhost:8686/jmxrmi|#]
However, in most cases, simply entering
host:port
is fine, such as, 192.168.1.150:8686. The long Service URL is not needed.Another host name can be substituted for
localhost
. The default port number (8686) could change if thejmx-connector
configuration has been modified. -
Click Connect.
In the JConsole window you will see all your MBeans, JVM information, and so on, in various tabs. Most of the useful MBeans are to be found in the
amx
andjava.lang
domains.
See Also
For more information about JConsole, see
http://docs.oracle.com/javase/8/docs/technotes/guides/management/jconsole.html
.
9 Administering Life Cycle Modules
This chapter provides procedures for administering life cycle modules in the Eclipse GlassFish 7 environment.
The following topics are addressed here:
Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.
About Life Cycle Modules
Life cycle modules, also known as initialization services, provide a means of running short or long duration Java-based tasks within the Eclipse GlassFish environment. These modules are automatically initiated at server startup and are notified at various phases of the server life cycle. Configured properties for a life cycle module are passed as properties during server initialization.
All life cycle module classes and interfaces are in the
as-install/modules/glassfish-api.jar
file.
A life cycle module listens for and performs its tasks in response to the following Eclipse GlassFish sequence of events:
-
Initialization. The server reads the configuration, initializes built-in subsystems (such as security and logging services), and creates the containers.
-
Startup. The server loads and initializes deployed applications.
-
Ready. The server begins servicing requests.
-
Shutdown. The server shuts down the applications and stops.
-
Termination. The server closes the containers, the built-in subsystems, and the server runtime environment.
These events are defined in the LifecycleEvent
class. For information
on creating life cycle modules, see "Developing
Lifecycle Listeners" in Eclipse GlassFish
Application Development Guide.
If the |
Configuring Life Cycle Modules
The following topics are addressed here:
To Create a Life Cycle Module
Use the create-lifecycle-module
subcommand in remote mode to create a
life cycle module.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create a new life cycle modules by using the
create-lifecycle-module
subcommand.Information about options and properties for the subcommand are included in this help page.
-
Restart the server for your changes to take effect.
See To Restart a Domain.
Example 9-1 Creating a Life Cycle Module
This example creates the customSetup
life cycle module :
asadmin> create-lifecycle-module --classname "com.acme.CustomSetup"
--classpath "/export/customSetup" --loadorder 1 --failurefatal=true
--description "this is a sample customSetup"
--property rmi="Server\=acme1\:7070":timeout=30 customSetup
Command create-lifecycle-module executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-lifecycle-module
at the command line.
To List Life Cycle Modules
Use the list-lifecycle-modules
subcommand in remote mode to list the
existing life cycle modules.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List life cycle modules by using the
list-lifecycle-modules
subcommand.
Example 9-2 Listing Life Cycle Modules
This example lists the existing life cycle modules.
asadmin> list-lifecycle-modules
WSTCPConnectorLCModule
Command list-lifecycle-modules executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-lifecycle-modules
at the command line.
To Update a Life Cycle Module
Use the set
subcommand to update an existing life cycle module.
-
List the properties that can be updated for a life cycle module by using the
get
subcommand.For example (single mode):
asadmin get "*" | grep sampleLCM applications.application.sampleLCMmodule.availability-enabled=false applications.application.sampleLCMmodule.directory-deployed=false applications.application.sampleLCMmodule.enabled=true applications.application.sampleLCMmodule.name=sampleLCMmodule applications.application.sampleLCMmodule.object-type=user applications.application.sampleLCMmodule.property.class-name=example.lc.SampleModule applications.application.sampleLCMmodule.property.classpath=/build/lcm.jar applications.application.sampleLCMmodule.property.is-failure-fatal=false applications.application.sampleLCMmodule.property.isLifecycle=true
-
Update a life cycle module by using the
set
subcommand. -
Restart the server for your changes to take effect.
See To Restart a Domain.
Example 9-3 Updating a Life Cycle Module
This example updates the classpath
property.
sadmin> set applications.application.sampleLCMmodule.
property.classpath=/build/lcm_new.jarapplications.application.
sampleLCMmodule.property.classpath=/build/lcm_new.jar
Command set executed successfully.
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 Life Cycle Module
Use the delete-lifecycle-module
subcommand in remote mode to delete a
life cycle module.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the current life cycle modules by using the
list-lifecycle-modules
subcommand. -
Delete a life cycle module by using the
delete-lifecycle-module
subcommand.
Example 9-4 Deleting a Life Cycle Module
This example deletes the customSetup
life cycle module.
asadmin> delete-lifecycle-module customSetup
Command delete-lifecycle-module executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-lifecycle-module
at the command line.
10 Administering Batch Jobs
This chapter provides procedures for administering batch jobs in the
Eclipse GlassFish environment by using the asadmin
command-line
utility.
The following topics are addressed here:
Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.
About Batch Jobs
Eclipse GlassFish provides a batch runtime for the scheduling and execution of batch jobs. Batch jobs are typically long-running, bulk-oriented tasks that contain a series of steps and can be executed without user interaction. Examples include billing, report generation, data format conversion, and image processing.
Batch applications submit jobs to the batch runtime and provide instructions about how and when to execute the steps. The batch runtime processes the steps as directed by job XML documents packaged with the applications and stores information about jobs in a job repository. In Eclipse GlassFish, the job repository is a database
For detailed information about batch jobs, batch processing, and the
batch processing framework, see
Batch Processing
in The Jakarta EE Tutorial. Also see
Java Specification Request 352:
Batch Applications for the Java Platform
(http://jcp.org/en/jsr/detail?id=352
). The specification defines the
programming model for batch applications and the runtime for scheduling
and executing batch jobs.
Viewing Batch Jobs
You can view detailed information about batch jobs, executions, and
steps. Users who log in to the asadmin
utility or to the
Administration Console as administrator are the only users who can view
details for all batch jobs submitted by all applications in the
Eclipse GlassFish environment.
The following tasks are used to view information about batch jobs:
To List Batch Jobs
Use the list-batch-jobs
subcommand in remote mode to list batch jobs
and job details.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List batch jobs by using the
list-batch-jobs
subcommand.
Example 10-1 Listing Batch Jobs
This example lists batch jobs for the default server instance, server
.
Use list-batch-jobs -l
to list additional details.
asadmin> list-batch-jobs
JOBNAME INSTANCECOUNT
payroll 9
bonus 6
Command list-batch-jobs executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-batch-jobs
at the command line.
To List Batch Job Executions
When the batch runtime executes a job, the execution is given a unique execution ID. An execution ID is similar to a process ID. A new execution is created the first time a job is started and every time the existing execution is restarted.
Use the list-batch-job-executions
subcommand in remote mode to list
batch job executions and execution details.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List batch job executions by using the
list-batch-job-executions
subcommand.
Example 10-2 Listing Batch Job Executions
This example lists batch job executions for the default server instance,
server
, and displays specific details. Use
list-batch-job-executions -l
to list additional details.
asadmin> list-batch-job-executions -o=jobname,executionid,batchstatus,exitstatus
JOBNAME EXECUTIONID BATCHSTATUS EXITSTATUS
payroll 9 COMPLETED COMPLETED
bonus 6 FAILED FAILED
Command list-batch-job-executions executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-batch-job-executions
at the command line.
To List Batch Job Steps
A batch job consists of one or more steps. A step is an independent and sequential phase of a batch job.
Use the list-batch-job-steps
subcommand in remote mode to list steps
and step details for a specific batch job execution.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the execution ID of an execution by using the
list-batch-job-executions
subcommand. -
List steps for a specific batch job execution by using the
list-batch-job-steps
subcommand.
Example 10-3 Listing Batch Job Steps
This example lists batch job steps and specific step details for a job
execution with the execution ID of 7
. The target is the default server
instance, server
. Use list-batch-job-steps -l
to list additional
details.
Some lines of output are omitted from this example for readability.
asadmin> list-batch-job-steps o=stepname,stepid,batchstatus,stepmetrics 7
STEPNAME STEPID BATCHSTATUS STEPMETRICS
prepare 7 COMPLETED METRICNAME VALUE
READ_COUNT 8
WRITE_COUNT 8
PROCESS_SKIP_COUNT 0
process 8 COMPLETED METRICNAME VALUE
READ_COUNT 8
WRITE_COUNT 8
PROCESS_SKIP_COUNT 0
...
Command list-batch-job-steps executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-batch-job-steps
at the command line.
Configuring the Batch Runtime
The batch runtime uses a data source and a managed executor service to
execute batch jobs. The data source stores information about current and
past jobs, and the managed executor service provides threads to jobs.
Batch runtime configuration data is stored in the config
element in
domain.xml
.
Eclipse GlassFish provides a default data source and managed executor
service for the execution of batch jobs. For the domain administration
server (DAS), the default data source is jdbc/TimerPool
and the
default managed executor service is
concurrent/defaultManagedExecutorService
. If you create a standalone
server instance or a standalone cluster, the default data source is
jdbc/__default
. You can configure the batch runtime to use different
resources.
For more information about data sources, see Administering Database Connectivity. For more information about managed executor services, see Configuring Managed Executor Services.
The following tasks are used to view and configure the batch runtime:
To List the Batch Runtime Configuration
Use the list-batch-runtime-configuration
subcommand in remote mode to
display the configuration of the batch runtime.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Display the configuration of the batch runtime by using the
list-batch-runtime-configuration
subcommand. -
If desired, use the
get
subcommand to view the attributes of the data source and managed executor service resources.For example (output omitted):
asdmin> get resources.jdbc-resource.jdbc/__TimerPool.* ... asdmin> get resources.managed-executor-service.concurrent/__defaultManagedExecutorService.* ...
Example 10-4 Listing the Batch Runtime Configuration
This example lists the configuration of the batch runtime for the
default server instance, server
.
asadmin> list-batch-runtime-configuration
DATASOURCELOOKUPNAME EXECUTORSERVICELOOKUPNAME
jdbc/__TimerPool concurrent/__defaultManagedExecutorService
Command list-batch-runtime-configuration executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-batch-runtime-configuration
at the command
line.
To Configure the Batch Runtime
Use the set-batch-runtime-configuration
subcommand in remote mode to
configure the batch runtime.
Do not change the data source after the first batch job has been submitted to the batch runtime for execution. If the data source must be changed, stop and restart the domain and then make the change before any jobs are started or restarted. However, once the data source has been changed, information stored in the previous data source becomes inaccessible. The managed executor service can be changed after a batch job has been submitted to the batch runtime without affecting execution of the job. |
-
Ensure that the server is running. Remote subcommands require a running server.
-
Configure the batch runtime by using the
set-batch-runtime-configuration
subcommand.
Example 10-5 Configuring the Batch Runtime
This example configures the batch runtime for the default server
instance, server
, to use an existing managed executor service named
concurrent/Executor1
.
asadmin> set-batch-runtime-configuration --executorservicelookupname concurrent/Executor1
Command set-batch-runtime-configuration executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help set-batch-runtime-configuration
at the command
line.
11 Administering Database Connectivity
This chapter provides procedures for performing database connectivity
tasks in the Eclipse GlassFish 7 environment by
using the asadmin
command-line utility.
The following topics are addressed here:
Instructions for accomplishing these tasks by using the Administration Console are contained in the Administration Console online help.
About Database Connectivity
A database management system (DBMS) provides facilities for storing, organizing, and retrieving data. The information in databases is often described as persistent data because it is saved on disk and exists after the application process ends. Most business applications store data in relational databases. Applications can access database information by using the Java Database Connectivity (JDBC) API.
The key elements of database connectivity are the following:
-
Database. The repository where data is stored for an enterprise. Java EE applications access relational databases through the JDBC API. For administration procedures, see Setting Up the Database.
-
JDBC Connection Pool. A JDBC connection pool is a group of reusable connections for a particular database. For administration procedures, see Administering JDBC Connection Pools.
-
JDBC Resource. A JDBC resource (data source) provides applications with a means of connecting to a database. To create a JDBC resource, specify the connection pool with which it is associated. Multiple JDBC resources can specify a single connection pool. A JDBC resource is identified by its Java Naming and Directory Interface (JNDI) name. For administration procedures, see Administering JDBC Resources.
-
JDBC Driver. A database driver is a software component that enables a Java application to interact with a database connectivity API . Each database requires its own driver. For administration procedures, see Integrating the JDBC Driver.
At runtime, the following sequence occurs when an application connects to a database:
-
The application gets the JDBC resource associated with the database by making a call through the JNDI API.
Using the JNDI name of the resource, the naming and directory service locates the JDBC resource. Each JDBC resource specifies a connection pool.
-
Using the JDBC resource, the application gets a database connection.
Eclipse GlassFish retrieves a physical connection from the connection pool that corresponds to the database. The pool defines connection attributes such as the database name (URL), user name, and password.
-
After the database connection is established, the application can read, modify, and add data to the database.
The application accesses the database by making calls to the JDBC API. The JDBC driver translates the application’s JDBC calls into the protocol of the database server.
-
When the application is finished accessing the database, the application closes the connection and returns the connection to the connection pool.
Setting Up the Database
Most applications use relational databases to store, organize, and retrieve data. Applications access relational databases through the Java Database Connectivity (JDBC) API.
The following topics are addressed here:
To Install the Database and Database Driver
-
Install a supported database product.
To see the current list of database products supported by Eclipse GlassFish, refer to the Eclipse GlassFish Release Notes.
-
Install a supported JDBC driver for the database product.
For a list of drivers supported by Eclipse GlassFish, see Configuration Specifics for JDBC Drivers.
-
Make the JDBC driver JAR file accessible to the domain administration server (DAS).
-
Create the database.
The application provider usually delivers scripts for creating and populating the database.
Next Steps
You are now ready to create a connection pool for the database, and a JDBC resource that points to the connection pool. See To Create a JDBC Connection Pool and To Create a JDBC Resource. The final step is to integrate the JDBC driver into an administrative domain as described in Integrating the JDBC Driver.
To Start the Database
Eclipse GlassFish includes an implementation of the Apache Derby
database, however, you can use any JDBC-compliant database. The database
is not started automatically when you start Eclipse GlassFish, so if you
have applications that require a database, you need to start Apache
Derby database manually by using the local start-database
subcommand.
Start the database by using the start-database
subcommand.
When the database server starts, or a client connects to it
successfully, the following files are created at the location that is
specified by the --dbhome
option:
-
The
derby.log
file contains the database server process log along with its standard output and standard error information. -
The database files contain your schema (for example, database tables).
Example 11-1 Starting a Database
This example starts the Apache Derby database on the host host1 and port 5001. [source]
asadmin> start-database --dbhost host1 --dbport 5001 --terse=true Starting database in the background. Log redirected to /opt/SUNWappserver/databases/javadb.log. Command start-database executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help start-database
at the command line.
To Stop the Database
Use the local stop-database
subcommand to stop the Apache Derby
database on a specified port. A single host can have multiple database
server processes running on different ports.
-
If necessary, notify users that the database is being stopped.
-
Stop the database by using the
stop-database
subcommand.
Example 11-2 Stopping a Database
This example stops the Apache Derby database on port 5001 of
localhost
.
asadmin> stop-database --dbhost=localhost --dbport=5001
onnection obtained for host: localhost, port number 5001.
Apache Derby Network Server - 10.2.2.1 - (538595) shutdown
at 2008-10-17 23:34:2 7.218 GMT
Command stop-database executed successfully.
Troubleshooting
For a laptop that roams between networks, you might have trouble
shutting down the database. If you start the Apache Derby database and
then change your IP address, you will not be able to stop the Apache
Derby database unless you add a specific --dbhost
argument. For
example, if you run asadmin start-database
dbhost
= 0.0.0.0
, and
then disconnect Ethernet and switch to wifi, you should run a command
similar to the following to stop the database:
asadmin stop-database
dbhost
localhost
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help stop-database
at the command line.
Apache Derby Database Utility Scripts
The Apache Derby database configuration that is available for use with
Eclipse GlassFish includes scripts that can help you use the Apache Derby
database. The following scripts are available in the
as-install/javadb/bin
directory:
startNetworkServer,startNetworkServer.bat
-
Script to start the network server
stopNetworkServer,stopNetworkServer.bat
-
Script to stop the network server
ij,ij.bat
-
Interactive JDBC scripting tool
dblook,dblook.bat
-
Script to view all or part of the DDL for a database
sysinfo, sysinfo.bat
-
Script to display versioning information about the Apache Derby database environment
NetworkServerControl,NetworkServerControl.bat
-
Script to execute commands on the
NetworkServerControl
API
To Configure Your Environment to Run the Apache Derby Database Utility Scripts
-
Ensure that the
JAVA_HOME
environment variable specifies the directory where the JDK is installed. -
Set the
JAVADB_HOME
environment variable to point to the as-install/javadb
directory.
See Also
For more information about these utilities, see the following documentation:
Configuring Access to the Database
After establishing the database, you are ready to set up access for Eclipse GlassFish applications. The high-level steps include creating a JDBC connection pool, creating a JDBC resource for the connection pool, and integrating a JDBC driver into an administrative domain.
Instructions for performing these steps are contained in the following sections:
Administering JDBC Connection Pools
A JDBC connection pool is a group of reusable connections for a particular database. Because creating each new physical connection is time consuming, Eclipse GlassFish maintains a pool of available connections. When an application requests a connection, it obtains one from the pool. When an application closes a connection, the connection is returned to the pool. JDBC connection pools can be globally accessible or be scoped to an enterprise application, web module, EJB module, connector module or application client module, as described in "Application-Scoped Resources" in Eclipse GlassFish Application Deployment Guide.
A JDBC resource is created by specifying the connection pool with which the resource is associated. Multiple JDBC resources can specify a single connection pool. The properties of connection pools can vary with different database vendors. Some common properties are the database name (URL), the user name, and the password.
The following tasks and information are used to administer JDBC connection pools:
To Create a JDBC Connection Pool
Use the create-jdbc-connection-pool
subcommand in remote mode to
register a new JDBC connection pool with the specified JDBC connection
pool name. A JDBC connection pool or a connector connection pool can be
created with authentication. You can either use a subcommand option to
specify user, password, or other connection information using the
asadmin
utility, or specify the connection information in the XML
descriptor file.
One connection pool is needed for each database, possibly more depending on the application. When you are building the connection pool, certain data specific to the JDBC driver and the database vendor is required. You can find some of the following specifics in Configuration Specifics for JDBC Drivers:
-
Database vendor name
-
Resource type, such as
javax.sql.DataSource
(local transactions only)javax.sql.XADataSource
(global transactions) -
Data source class name
-
Required properties, such as the database name (URL), user name, and password
Creating a JDBC connection pool is a dynamic event and does not require server restart. However, there are some parameters that do require server restart. See Configuration Changes That Require Restart.
Before You Begin
Before creating the connection pool, you must first install and integrate the database and its associated JDBC driver. For instructions, see Setting Up the Database.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create the JDBC connection pool by using the
create-jdbc-connection-pool
subcommand. -
If needed, restart the server.
Some parameters require server restart. See Configuration Changes That Require Restart.
Example 11-3 Creating a JDBC Connection Pool
This example creates a JDBC connection pool named sample_derby_pool
on
localhost
.
asadmin> create-jdbc-connection-pool
--datasourceclassname org.apache.derby.jdbc.ClientDataSource
--restype javax.sql.XADataSource
--property portNumber=1527:password=APP:user=APP:serverName=
localhost:databaseName=sun-appserv-samples:connectionAttribut
es=\;create\\=true sample_derby_pool
Command create-jdbc-connection-pool executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-jdbc-connection-pool
at the command line.
To List JDBC Connection Pools
Use the list-jdbc-connection-pools
subcommand in remote mode to list
all existing JDBC connection pools.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the JDBC connection pools by using the
list-jdbc-connection-pools
subcommand.
Example 11-4 Listing JDBC Connection Pools
This example lists the JDBC connection pools that are on localhost
.
asadmin> list-jdbc-connection-pools
sample_derby_pool2
poolA
__TimerPool
DerbyPool
sample_derby_pool
Command list-jdbc-connection-pools executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-jdbc-connection-pools
at the command line.
To Contact (Ping) a Connection Pool
Use the ping-connection-pool
subcommand in remote mode to test if a
connection pool is usable. For example, if you create a new JDBC
connection pool for an application that is expected to be deployed
later, you can test the JDBC pool with this subcommand before the
application is deployed. Running a ping will force the creation of the
pool if it hasn’t already been created.
Before You Begin
Before you can contact a connection pool, the connection pool must be created with authentication, and the server or database must be running.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Ping a connection pool by using the
ping-connection-pool
subcommand.
Example 11-5 Contacting a Connection Pool
This example tests to see if the DerbyPool
connection pool is usable.
asadmin> ping-connection-pool DerbyPool
Command ping-connection-pool executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help ping-connection-pool
at the command line.
You can also specify that a JDBC connection pool is automatically tested
when created or reconfigured by setting its --ping
option to true
(the default is false
). See To Create a JDBC Connection
Pool or To Update a JDBC Connection Pool.
To Reset (Flush) a Connection Pool
Use the flush-connection-pool
in remote mode to reinitialize all
connections established in the specified connection pool without the
need for reconfiguring the pool. Connection pool reconfiguration can
result in application redeployment, which is a time-consuming operation.
The JDBC connection pool or connector connection pool is reset to its
initial state. Any existing live connections are destroyed, which means
that the transactions associated with these connections are lost and
must be retried. The subcommand then recreates the initial connections
for the pool, and restores the pool to its steady pool size.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Reset a connection pool by using the
flush-connection-pool
subcommand.
Example 11-6 Resetting (Flushing) a Connection Pool
This example resets the JDBC connection pool named __TimerPool
to its
steady pool size.
asadmin> flush-connection-pool __TimerPool
Command flush-connection-pool executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help flush-connection-pool
at the command line.
To Update a JDBC Connection Pool
You can change all of the settings for an existing pool except its name.
Use the get
and set
subcommands to view and change the values of the
JDBC connection pool properties.
-
List the JDBC connection pools by using the
list-jdbc-connection-pools
subcommand. -
View the attributes of the JDBC connection pool by using the get subcommand.
For example:
asadmin get resources.jdbc-connection-pool.DerbyPool.property
-
Set the attribute of the JDBC connection pool by using the set subcommand.
For example:
asadmin set resources.jdbc-connection-pool.DerbyPool.steady-pool-size=9
-
If needed, restart the server.
Some parameters require server restart. See Configuration Changes That Require Restart.
See Also
For information about how to tune a connection pool, see the Eclipse GlassFish Performance Tuning Guide.
To Delete a JDBC Connection Pool
Use the delete-jdbc-connection-pool
subcommand in remote mode to
delete an existing JDBC connection pool. Deleting a JDBC connection pool
is a dynamic event and does not require server restart.
Before You Begin
Before deleting a JDBC connection pool, all associations to the resource must be removed.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the JDBC connection pools by using the
list-jdbc-connection-pools
subcommand. -
If necessary, notify users that the JDBC connection pool is being deleted.
-
Delete the connection pool by using the
delete-jdbc-connection-pool
subcommand.
Example 11-7 Deleting a JDBC Connection Pool
This example deletes the JDBC connection pool named DerbyPool
.
asadmin> delete-jdbc-connection-pool jdbc/DerbyPool
Command delete-jdbc-connection-pool executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-jdbc-connection-pool
at the command line.
Configuring Specific JDBC Connection Pool Features
In Eclipse GlassFish, JDBC Connection Pools support a variety of features to simplify administration, monitoring and performance tuning. The following topics address several of these features:
Transparent Pool Reconfiguration
When the properties or attributes of a JDBC connection pool are changed, the connection pool is destroyed and re-created. Normally, applications using the connection pool must be redeployed as a consequence. This restriction can be avoided by enabling transparent JDBC connection pool reconfiguration. When this feature is enabled, applications do not need to be redeployed. Instead, requests for new connections are blocked until the reconfiguration operation completes. Connection requests from any in-flight transactions are served using the old pool configuration so as to complete the transaction. Then, connections are created using the pool’s new configuration, and any blocked connection requests are served with connections from the re-created pool.
To enable transparent JDBC connection pool reconfiguration, set the
dynamic-reconfiguration-wait-timeout-in-seconds
property of the JDBC
connection pool to a positive, nonzero value in one of the following
ways:
-
Add it as a property in the Edit JDBC Connection Pool Properties page in the Administration Console. For more information, click the Help button in the Administration Console.
-
Specify it using the
--property
option in thecreate-jdbc-connection-pool
subcommand. For more information, seecreate-jdbc-connection-pool
(1). -
Set it using the
set
subcommand. For example:asadmin set resources.jdbc-connection-pool.pool-name.property.dynamic-reconfiguration-wait-timeout-in-seconds=15
This property specifies the time in seconds to wait for in-use connections to close and in-flight transactions to complete. Any connections in use or transaction in flight past this time must be retried.
Using an Initialization Statement
You can specify a statement that executes each time a physical connection to the database is created (not reused) from a JDBC connection pool. This is useful for setting request or session specific properties and is suited for homogeneous requests in a single application. Set the Init SQL attribute of the JDBC connection pool to the SQL string to be executed in one of the following ways:
-
Enter an Init SQL value in the Edit Connection Pool Advanced Attributes page in the Administration Console. For more information, click the Help button in the Administration Console.
-
Specify the
--initsql
option in theasadmin create-jdbc-connection-pool
command. For more information, seecreate-jdbc-connection-pool
(1). -
Specify the
init-sql
option in theasadmin set
command. For example:asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.init-sql="sql-string"
Setting a Statement Timeout
An abnormally long running JDBC query executed by an application may
leave it in a hanging state unless a timeout is explicitly set on the
statement. Setting a statement timeout guarantees that all queries
automatically time out if not completed within the specified period.
When statements are created, the queryTimeout
is set according to the
statement timeout setting. This works only when the underlying JDBC
driver supports queryTimeout
for Statement
, PreparedStatement
,
CallableStatement
, and ResultSet
.
You can specify a statement timeout in the following ways:
-
Enter a Statement Timeout value in the Edit Connection Pool Advanced Attributes page in the Administration Console. For more information, click the Help button in the Administration Console.
-
Specify the
--statementtimeout
option in theasadmin create-jdbc-connection-pool
command. For more information, seecreate-jdbc-connection-pool
(1).
Statement Leak Detection and Leaked Statement Reclamation
If statements are not closed by an application after use, it is possible for the application to run out of cursors. Enabling statement leak detection causes statements to be considered as leaked if they are not closed within a specified period. Additionally, leaked statements can reclaimed automatically.
To enable statement leak detection, set Statement Leak Timeout In Seconds for the JDBC connection pool to a positive, nonzero value in one of the following ways:
-
Specify the
--statementleaktimeout
option in thecreate-jdbc-connection-pool
subcommand. For more information, seecreate-jdbc-connection-pool
(1). -
Specify the
statement-leak-timeout-in-seconds
option in theset
subcommand. For example:asadmin set resources.jdbc-connection-pool.pool-name.statement-leak-timeout-in-seconds=300
When selecting a value for Statement Leak Timeout In Seconds, make sure that:
-
It is less than the Connection Leak Timeout; otherwise, the connection could be closed before the statement leak is recognized.
-
It is greater than the Statement Timeout; otherwise, a long running query could be mistaken as a statement leak.
After enabling statement leak detection, enable leaked statement
reclamation by setting Reclaim Leaked Statements for the JDBC connection
pool to a true
value in one of the following ways:
-
Specify the
--statementleakreclaim=true
option in thecreate-jdbc-connection-pool
subcommand. For more information, seecreate-jdbc-connection-pool
(1). -
Specify the
statement-leak-reclaim
option in theset
subcommand. For example:asadmin set resources.jdbc-connection-pool.pool-name.statement-leak-reclaim=true
Statement Caching
Statement caching stores statements, prepared statements, and callable statements that are executed repeatedly by applications in a cache, thereby improving performance. Instead of the statement being prepared each time, the cache is searched for a match. The overhead of parsing and creating new statements each time is eliminated.
Statement caching is usually a feature of the JDBC driver. The Eclipse GlassFish provides caching for drivers that do not support caching. To enable this feature, set the Statement Cache Size for the JDBC connection pool in one of the following ways:
-
Enter a Statement Cache Size value in the Edit Connection Pool Advanced Attributes page in the Administration Console. For more information, click the Help button in the Administration Console.
-
Specify the
--statementcachesize
option in theasadmin create-jdbc-connection-pool
command. For more information, seecreate-jdbc-connection-pool
(1). -
Specify the
statement-cache-size
option in theasadmin set
command. For example:asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.statement-cache-size=10
By default, this attribute is set to zero and the statement caching is turned off. To enable statement caching, you can set any positive nonzero value. The built-in cache eviction strategy is LRU-based (Least Recently Used). When a connection pool is flushed, the connections in the statement cache are recreated.
Statement Tracing
You can trace the SQL statements executed by applications that use a JDBC connection pool. Set the SQL Trace Listeners attribute to a comma-separated list of trace listener implementation classes in one of the following ways:
-
Enter an SQL Trace Listeners value in the Edit Connection Pool Advanced Attributes page in the Administration Console. For more information, click the Help button in the Administration Console.
-
Specify the
--sqltracelisteners
option in theasadmin create-jdbc-connection-pool
command. For more information, seecreate-jdbc-connection-pool
(1). -
Specify the
sql-trace-listeners
option in theasadmin set
command. For example:asadmin set domain1.resources.jdbc-connection-pool.DerbyPool.sql-trace-listeners=listeners
The Eclipse GlassFish provides a public interface,
org.glassfish.api.jdbc.SQLTraceListener , that implements a means of
recording SQLTraceRecord
objects. To make custom implementations of
this interface available to the Eclipse GlassFish, place the
implementation classes in as-install/lib
.
The Eclipse GlassFish provides an SQL tracing logger to log the SQL
operations in the form of SQLTraceRecord
objects in the server.log
file. The module name under which the SQL operation is logged is
jakarta.enterprise.resource.sqltrace
. SQL traces are logged as FINE
messages along with the module name to enable easy filtering of the SQL
logs. A sample SQL trace record looks like this:
[#|2009-11-27T15:46:52.202+0530|FINE|glassfish7.0|jakarta.enterprise.resource.sqltrace.com.sun.gjc.util
|_ThreadID=29;_ThreadName=Thread-1;ClassName=com.sun.gjc.util.SQLTraceLogger;MethodName=sqlTrace;
|ThreadID=77 | ThreadName=p: thread-pool-1; w: 6 | TimeStamp=1259317012202
| ClassName=com.sun.gjc.spi.jdbc40.PreparedStatementWrapper40 | MethodName=executeUpdate
| arg[0]=insert into table1(colName) values(100) | arg[1]=columnNames | |#]
This trace shows that an executeUpdate(String sql, String columnNames)
operation is being done.
When SQL statement tracing is enabled and JDBC connection pool monitoring is enabled, Eclipse GlassFish maintains a tracing cache of recent queries and their frequency of use. The following JDBC connection pool properties can be configured to control this cache and the monitoring statistics available from it:
time-to-keep-queries-in-minutes
-
Specifies how long in minutes to keep a query in the tracing cache, tracking its frequency of use. The default value is 5 minutes.
number-of-top-queries-to-report
-
Specifies how many of the most used queries, in frequency order, are listed the monitoring report. The default value is 10 queries.
Set these parameters in one of the following ways:
-
Add them as properties in the Edit JDBC Connection Pool Properties page in the Administration Console. For more information, click the Help button in the Administration Console.
-
Specify them using the
--property
option in thecreate-jdbc-connection-pool
subcommand. For more information, seecreate-jdbc-connection-pool
(1). -
Set them using the
set
subcommand. For example:asadmin set resources.jdbc-connection-pool.pool-name.property.time-to-keep-queries-in-minutes=10
Administering JDBC Resources
A JDBC resource, also known as a data source, provides an application with a means of connecting to a database. Typically, you create a JDBC resource for each database that is accessed by the applications deployed in a domain. Multiple JDBC resources can be specified for a database. JDBC resources can be globally accessible or be scoped to an enterprise application, web module, EJB module, connector module or application client module, as described in "Application-Scoped Resources" in Eclipse GlassFish Application Deployment Guide.
A JDBC resource is created by specifying the connection pool with which
the resource will be associated . Use a unique Java Naming and Directory
Interface (JNDI) name to identify the resource. For example, the JNDI
name for the resource of a payroll database might be
java:comp/env/jdbc/payrolldb
.
The Jakarta EE standard specifies that certain default resources be made
available to applications, and defines specific JNDI names for these
default resources. Eclipse GlassFish makes these names available through
the use of logical JNDI names, which map Jakarta EE standard JNDI names to
specific Eclipse GlassFish resources. For JDBC resources, the Jakarta EE
standard name java:comp/DefaultDataSource
is mapped to the
jdbc/__default
resource.
The following tasks and information are used to administer JDBC resources:
To Create a JDBC Resource
Use the create-jdbc-resource
subcommand in remote mode to create a
JDBC resource. Creating a JDBC resource is a dynamic event and does not
require server restart.
Because all JNDI names are in the java:comp/env
subcontext, when
specifying the JNDI name of a JDBC resource in the Administration
Console, use only the jdbc/`name format. For example, a payroll
database might be specified as `jdbc/payrolldb
.
Before You Begin
Before creating a JDBC resource, you must first create a JDBC connection pool. For instructions, see To Create a JDBC Connection Pool.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create a JDBC resource by using the
create-jdbc-resource
subcommand.Information about properties for the subcommand is included in this help page.
-
If necessary, notify users that the new resource has been created.
Example 11-8 Creating a JDBC Resource
This example creates a JDBC resource named DerbyPool
.
asadmin> create-jdbc-resource --connectionpoolid DerbyPool jdbc/DerbyPool
Command create-jdbc-resource executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-jdbc-resource
at the command line.
To List JDBC Resources
Use the list-jdbc-resources
subcommand in remote mode to list the
existing JDBC resources.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List JDBC resources by using the
list-jdbc-resources
subcommand.
Example 11-9 Listing JDBC Resources
This example lists JDBC resources for localhost
.
asadmin> list-jdbc-resources
jdbc/__TimerPool
jdbc/DerbyPool
jdbc/__default
jdbc1
Command list-jdbc-resources executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-jdbc-resources
at the command line.
To Update a JDBC Resource
You can enable or disable a JDBC resource by using the set
subcommand.
The JDBC resource is identified by its dotted name.
-
List JDBC resources by using the
list-jdbc-resources
subcommand. -
Modify the values for the specified JDBC resource by using the
set
subcommand.For example:
Example 11-10 Updating a JDBC Resource
This example changes the res1
enabled setting to false.
asadmin>set resources.jdbc-resource.res1.enabled=false
To Delete a JDBC Resource
Use the delete-jdbc-resource
subcommand in remote mode to delete an
existing JDBC resource. Deleting a JDBC resource is a dynamic event and
does not require server restart.
Before You Begin
Before deleting a JDBC resource, all associations with this resource must be removed.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List JDBC resources by using the
list-jdbc-resources
subcommand. -
If necessary, notify users that the JDBC resource is being deleted.
-
Delete a JDBC resource by using the
delete-jdbc-resource
subcommand.
Example 11-11 Deleting a JDBC Resource
This example deletes a JDBC resource named DerbyPool
.
asadmin> delete-jdbc-resource jdbc/DerbyPool
Command delete-jdbc-resource executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-jdbc-resource
at the command line.
Enabling the jdbc/__default
Resource in a Clustered Environment
Eclipse GlassFish 7 includes a preconfigured JDBC resource with the
JNDI name jdbc/default
. This jdbc/default
resource is not
enabled by default, so you need to explicitly enable it if you want to
use it in a cluster.
To Enable the jdbc/__default
Resource for a Clustered Environment
Instructions for creating JDBC resources in general are provided in
To Create a JDBC Resource. Use the following procedure to
enable the preconfigured jdbc/__default
resource for a clustered
Eclipse GlassFish environment.
-
Create the
jdbc/__default
resource reference for the cluster.asadmin create-resource-ref --target cluster-name jdbc/__default
-
Enable the resource on the DAS that manages the cluster.
asadmin set resources.jdbc-connection-pool.DerbyPool.property.serverName=DAS-machine-name
This step is only required if the cluster includes remote instances.
-
Restart the DAS and the target cluster(s).
asadmin stop-cluster cluster-name asadmin stop-domain domain-name asadmin start-domain domain-name asadmin start-cluster cluster-name
Integrating the JDBC Driver
To use JDBC features, you must choose a JDBC driver to work with the Eclipse GlassFish, then you must set up the driver. This section covers these topics:
Supported Database Drivers
Supported JDBC drivers are those that have been fully tested by Oracle. For a list of the JDBC drivers currently supported by the Eclipse GlassFish, see the Eclipse GlassFish Release Notes. For configurations of supported and other drivers, see Configuration Specifics for JDBC Drivers.
Because the drivers and databases supported by the Eclipse GlassFish are constantly being updated, and because database vendors continue to upgrade their products, always check with Oracle technical support for the latest database support information. |
Making the JDBC Driver JAR Files Accessible
To integrate the JDBC driver into a Eclipse GlassFish domain, copy the
JAR files into the domain-dir/lib
directory, then restart the server.
This makes classes accessible to all applications or modules deployed on
servers that share the same configuration. For more information about
Eclipse GlassFish class loaders, see "Class Loaders" in
Eclipse GlassFish Application Development Guide.
If you are using an Oracle database with EclipseLink extensions, copy
the JAR files into the domain-dir/lib/ext
directory, then restart the
server. For details, see "Oracle Database
Enhancements" in Eclipse GlassFish Application
Development Guide.
Automatic Detection of Installed Drivers
The Administration Console detects installed JDBC Drivers automatically when you create a JDBC connection pool. To create a JDBC connection pool using the Administration Console, open the Resources component, open the JDBC component, select Connection Pools, and click on the New button. This displays the New JDBC Connection Pool page.
Based on the Resource Type and Database Vendor you select on the New JDBC Connection Pool page, data source or driver implementation class names are listed in the Datasource Classname or Driver Classname field when you click on the Next button. When you choose a specific implementation class name on the next page, additional properties relevant to the installed JDBC driver are displayed in the Additional Properties section.
Configuration Specifics for JDBC Drivers
Eclipse GlassFish is designed to support connectivity to any database management system by using a corresponding JDBC driver. Configuration information is provided for these JDBC drivers:
IBM DB2 Database Type 2 Driver
The JAR files for the DB2 driver are db2jcc.jar
,
db2jcc_license_cu.jar
, and db2java.zip
. Set your environment
variables . For example:
LD_LIBRARY_PATH=/usr/db2user/sqllib/lib:${Jakarta EE.home}/lib
DB2DIR=/opt/IBM/db2/V8.2
DB2INSTANCE=db2user
INSTHOME=/usr/db2user
VWSPATH=/usr/db2user/sqllib
THREADS_FLAG=native
Configure the connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: DB2
-
DataSource Classname:
com.ibm.db2.jcc.DB2SimpleDataSource
-
Properties:
-
databaseName
- Set as appropriate. -
user
- Set as appropriate. -
password
- Set as appropriate. -
driverType
- Set to2
. -
deferPrepares
- Set tofalse
.
-
IBM DB2 Database Type 4 Driver
The JAR file for the DB2 driver is db2jcc.jar
. Configure the
connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: DB2
-
DataSource Classname:
com.ibm.db2.jcc.DB2SimpleDataSource
-
Properties:
-
databaseName
- Set as appropriate. -
user
- Set as appropriate. -
password
- Set as appropriate. -
driverType
- Set to4
.
-
Apache Derby DB/Derby Type 4 Driver
The Apache Derby DB/Derby JDBC driver is included with Eclipse GlassFish by default, so you do not need to integrate this JDBC driver with Eclipse GlassFish.
The JAR file for the Apache Derby DB driver is derbyclient.jar
.
Configure the connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: Apache Derby
-
DataSource Classname: Specify one of the following:
org.apache.derby.jdbc.ClientDataSource40 org.apache.derby.jdbc.ClientXADataSource40
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server if it is different from the default. -
databaseName
- Specify the name of the database. -
user
- Specify the database user.This is only necessary if the Apache Derby database is configured to use authentication. The Apache Derby database does not use authentication by default. When the user is provided, it is the name of the schema where the tables reside.
-
password
- Specify the database password.This is only necessary if the Apache Derby database is configured to use authentication.
-
MySQL Server Database Type 4 Driver
The JAR file for the MySQL driver is
mysql-connector-java-5.1.14-bin.jar
. Configure the connection pool
using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: MySql
-
DataSource Classname:
com.mysql.jdbc.jdbc2.optional.MysqlDataSource com.mysql.jdbc.jdbc2.optional.MysqlXADataSource
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server. -
databaseName
- Set as appropriate. -
user
- Set as appropriate. -
password
- Set as appropriate.
-
Oracle 10 Database Driver
The JAR file for the Oracle 10 database driver is ojdbc14.jar
. Make
sure that the shared library is available through LD_LIBRARY_PATH
and
that the ORACLE_HOME
property is set.
To make the Oracle driver behave in a Jakarta EE-compliant manner, you must define the following JVM property:
-Doracle.jdbc.J2EE13Compliant=true
Configure the connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: Oracle
-
DataSource Classname: Specify one of the following:
oracle.jdbc.pool.OracleDataSource oracle.jdbc.xa.client.OracleXADataSource
-
Properties:
-
user
- Set as appropriate. -
password
- Set as appropriate.
-
Oracle 11 Database Driver
The JAR file for the Oracle 11 database driver is ojdbc6.jar
.
To make the Oracle driver behave in a Jakarta EE-compliant manner, you must define the following JVM property:
-Doracle.jdbc.J2EE13Compliant=true
Configure the connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: Oracle
-
DataSource Classname: Specify one of the following:
oracle.jdbc.pool.OracleDataSource oracle.jdbc.xa.client.OracleXADataSource
-
Properties:
-
user
- Set as appropriate. -
password
- Set as appropriate.For this driver, the
XAResource.recover
method repeatedly returns the same set of in-doubt Xids regardless of the input flag. According to the XA specifications, the Transaction Manager initially calls this method withTMSTARTSCAN
and then withTMNOFLAGS
repeatedly until no Xids are returned. TheXAResource.commit
method also has some issues.To disable this Eclipse GlassFish workaround, the
oracle-xa-recovery-workaround
property value must be set tofalse
.Additionally, in order for the transaction manager to recover transactions, the JDBC connection pool’s database user must be given certain Oracle permissions:
-
SELECT permission on DBA_PENDING_TRANSACTIONS, PENDING_TRANS$, DBA_2PC_PENDING and DBA_2PC_NEIGHBORS.
-
EXECUTE permissions on DBMS_XA and DBMS_SYSTEM.
-
-
PostgreSQL Type 4 Driver
The JAR file for the PostgreSQL driver is
postgresql-9.0-801.jdbc4.jar
. Configure the connection pool using the
following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: Postgresql
-
DataSource Classname:
org.postgresql.ds.PGSimpleDataSource
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server. -
databaseName
- Set as appropriate. -
user
- Set as appropriate. -
password
- Set as appropriate.
-
DataDirect Type 4 Driver for IBM DB2 Database
The JAR file for DataDirect driver is db2.jar
. Configure the
connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: DataDirect-DB2
-
DataSource Classname:
com.ddtek.jdbcx.db2.DB2DataSource
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server. -
databaseName
- Set as appropriate. -
user
- Set as appropriate. -
password
- Set as appropriate.
-
DataDirect Type 4 Driver for IBM Informix
Configure the connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: DataDirect-Informix
-
DataSource Classname: Specify one of the following:
com.informix.jdbcx.IfxDataSource com.informix.jdbcx.IfxXADataSource
DataDirect DataSource Classname:
com.ddtek.jdbcx.informix.InformixDataSourcee
-
Properties:
-
serverName
- Specify the Informix database server name. -
portNumber
- Specify the port number of the database server. -
databaseName
- Set as appropriate. This is optional. -
user
- Set as appropriate. -
password
- Set as appropriate. -
IfxIFXHost
- Specify the host name or IP address of the database server.
-
DataDirect Type 4 Driver for Microsoft SQL Server Database
The JAR file for the DataDirect driver is sqlserver.jar
. Configure the
connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: DataDirect-Microsoft SQL Server
-
DataSource Classname:
com.ddtek.jdbcx.sqlserver.SQLServerDataSource
-
Properties:
-
serverName
- Specify the host name or IP address and the port of the database server. -
portNumber
- Specify the port number of the database server. -
user
- Set as appropriate. -
password
- Set as appropriate. -
selectMethod
- Set tocursor
.
-
DataDirect Type 4 Driver for MySQL Server Database
The JAR file for the DataDirect driver is mysql.jar
. Configure the
connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: DataDirect-MySQL
-
DataSource:
com.ddtek.jdbcx.mysql.MySQLDataSource
-
Properties:
-
serverName
- Specify the host name or IP address and the port of the database server. -
portNumber
- Specify the port number of the database server. -
user
- Set as appropriate. -
password
- Set as appropriate. -
selectMethod
- Set tocursor
.
-
DataDirect Type 4 Driver for Oracle 11 Database
The JAR file for the DataDirect driver is oracle.jar
.
To make the Oracle driver behave in a Jakarta EE-compliant manner, you must define the following JVM property:
-Doracle.jdbc.J2EE13Compliant=true
Configure the connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: DataDirect-Oracle
-
DataSource Classname:
com.ddtek.jdbcx.oracle.OracleDataSource
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server. -
user
- Set as appropriate. -
password
- Set as appropriate.
-
DataDirect Type 4 Driver for Sybase Database
The JAR file for the DataDirect driver is sybase.jar
. Configure the
connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: DataDirect-Sybase
-
DataSource Classname:
com.ddtek.jdbcx.sybase.SybaseDataSource
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server. -
databaseName
- Set as appropriate. This is optional. -
user
- Set as appropriate. -
password
- Set as appropriate.
-
In some situations, using this driver can cause exceptions to be thrown
because the driver creates a stored procedure for every parameterized
PreparedStatement by default. If this situation arises, add the property
|
Inet Oraxo Driver for Oracle Database
The JAR file for the Inet Oracle driver is Oranxo.jar
. Configure the
connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: Oracle
-
DataSource Classname:
com.inet.ora.OraDataSource
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server. -
user
- Specify the database user. -
password
- Specify the database password. -
serviceName
- Specify the URL of the database. The syntax is as follows:jdbc:inetora:server:port:dbname
For example:
jdbc:inetora:localhost:1521:payrolldb
In this example,
localhost
is the name of the host running the Oracle server,1521
is the Oracle server’s port number, andpayrolldb
is the SID of the database. For more information about the syntax of the database URL, see the Oracle documentation. -
streamstolob
- If the size of BLOB or CLOB data types exceeds 4 KB and this driver is used for CMP, this property must be set totrue
.
-
Inet Merlia Driver for Microsoft SQL Server Database
The JAR file for the Inet Microsoft SQL Server driver is Merlia.jar
.
Configure the connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: MicrosoftSqlServer
-
DataSource Classname:
com.inet.tds.TdsDataSource
-
Properties:
-
serverName
- Specify the host name or IP address and the port of the database server. -
portNumber
- Specify the port number of the database server. -
user
- Set as appropriate. -
password
- Set as appropriate.
-
Inet Sybelux Driver for Sybase Database
The JAR file for the Inet Sybase driver is Sybelux.jar
. Configure the
connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: Sybase
-
DataSource Classname:
com.inet.syb.SybDataSource
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server. -
databaseName
- Set as appropriate. Do not specify the complete URL, only the database name. -
user
- Set as appropriate. -
password
- Set as appropriate.
-
JConnect Type 4 Driver for Sybase ASE 12.5 Database
The JAR file for the Sybase driver is jconn4.jar
. Configure the
connection pool using the following settings:
-
Name: Use this name when you configure the JDBC resource later.
-
Resource Type: Specify the appropriate value.
-
Database Vendor: Sybase
-
DataSource Classname: Specify one of the following:
com.sybase.jdbc4.jdbc.SybDataSource com.sybase.jdbc4.jdbc.SybXADataSource
-
Properties:
-
serverName
- Specify the host name or IP address of the database server. -
portNumber
- Specify the port number of the database server. -
databaseName
- Set as appropriate. Do not specify the complete URL, only the database name. -
user
- Set as appropriate. -
password
- Set as appropriate. -
BE_AS_JDBC_COMPLIANT_AS_POSSIBLE
- Set totrue
. -
FAKE_METADATA
- Set totrue
.
-
12 Administering EIS Connectivity
This chapter provides information and procedures for administering
connections to enterprise information system (EIS) data in the Eclipse GlassFish 7 environment by using the asadmin
command-line utility.
If you installed the Web Profile, connector modules that use only outbound communication features and work-management that does not involve inbound communication features are supported. Other connector features are supported only in the Full Platform Profile. |
The following topics are addressed here:
Instructions for accomplishing the tasks in this chapter by using the Administration Console are contained in the Administration Console online help.
For information about database connectivity, see Administering Database Connectivity.
About EIS Connectivity
Enterprise information system (EIS) refers to any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. Connection resources are used by applications and modules to access EIS software.)
The key elements of EIS connectivity are the following:
-
Connector Module. A connector module, also called a resource adapter, is a Jakarta EE component that enables applications to interact with EIS software. A connector module is used by Eclipse GlassFish to implement Java Message Service (JMS). Like other Jakarta EE modules, a connector module is installed when it is deployed. For instructions on creating a connector module, see "Developing Connectors" in Eclipse GlassFish Application Development Guide.
-
Connector Connection Pool. A connector connection pool is a group of reusable connections for a particular EIS. A connector connection pool is created when you specify the connector module that is associated with the pool. For administration procedures, see Administering Connector Connection Pools.
-
Connector Resource. A connector resource is a program object that provides an application with a connection to an EIS. A connector resource is created when you specify its JNDI name and its associated connection pool. The JNDI name of a connector resource for an EIS is usually in the `java:comp/env/`eis-specific subcontext. For administration procedures, see Administering Connector Resources.
-
Connector Module Configuration. A connector module configuration is the information that resides in the domain configuration file (
domain.xml
) for the particular connector module (resource adapter). For administration procedures, see Administering the Resource Adapter Configuration. -
Connector Security Map. A connector security map associates the caller identity of the application (principal or user group) to a suitable EIS principal or group. For administration procedures, see Administering Connector Security Maps.
-
Connector Work Security Map. A connector work security map associates the caller identity of the work submitted by the connector module (resource adapter) EIS principal or EIS user group to a suitable principal or user group in the Eclipse GlassFish security domain. For administration procedures, see Administering Connector Work Security Maps.
-
Administered Object. An administered object provides specialized functionality for an application, such as providing access to a parser that is specific to the connector module and its associated EIS. For administration procedures, see Administering Administered Objects.
At runtime, the following sequence occurs when an application connects to an EIS:
-
The application gets the connector resource (data source) associated with the EIS by making a call through the JNDI API.
Using the JNDI name of the connector resource, the naming and directory service locates the resource. Each EIS resource specifies a connector connection pool.
-
Using the connector resource, the application gets an EIS connection.
Eclipse GlassFish retrieves a physical connection from the connection pool that corresponds to the EIS resource. The pool defines connection attributes such as the EIS name, user name, and password.
-
After the EIS connection is established, the application can read, modify, and add data to the EIS.
The application accesses the EIS information by making calls to the JMS API.
-
When the application is finished accessing the EIS, the application closes the connection and returns the connection to the connection pool.
Administering Connector Connection Pools
After a connector module has been deployed, you are ready to create a connector connection pool for it.
The following topics are addressed here:
To Create a Connector Connection Pool
Use the create-connector-connection-pool
subcommand in remote mode to
create a connector connection pool for a deployed connector module. When
you are building the connector connection pool, certain data specific to
the EIS will be required. The value in the mandatory
--connectiondefintion
option provides the EIS info.
Multiple connector resources can specify a single connection pool.
Creating a connector connection pool is a dynamic event and does not require server restart. However, there are some parameters that do require server restart. See Configuration Changes That Require Restart.
Before You Begin
Before creating the connector connection pool, the connector must be installed.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create the connector connection pool by using the
create-connector-connection-pool
subcommand.Information about properties for the subcommand is included in this help page.
-
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
-
You can verify that a connection pool is usable by using the
ping-connection-pool
subcommand.For instructions, see To Contact (Ping) a Connection Pool.
Example 12-1 Creating a Connector Connection Pool
This example creates the new jms/qConnPool
pool for the
jakarta.jms.QueueConnectionFactory
connector module.
asadmin> create-connector-connection-pool --steadypoolsize 20 --maxpoolsize 100
--poolresize 2 --maxwait 60000 --raname jmsra --connectiondefinition
jakarta.jms.QueueConnectionFactory jms/qConnPool
Command create-connector-connection-pool executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-connector-connection-pool
at the command
line.
To List Connector Connection Pools
Use the list-connector-connection-pools
subcommand in remote mode to
list the pools that have been created.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the connector connection pools by using the
list-connector-connection-pools
subcommand.
Example 12-2 Listing Connector Connection Pools
This example lists the existing connector connection pools.
asadmin> list-connector-connection-pools
jms/qConnPool
Command list-connector-connection-pools executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-connector-connection-pools
at the command
line.
To Connect to (Ping) or Reset (Flush) a Connector Connection Pool
Use the ping-connection-pool
or flush-connection-pool
subcommands in
remote mode to perform these tasks on a connection pools. See
To Contact (Ping) a Connection Pool or
To Reset (Flush) a Connection Pool for
instructions.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Connect to or reset a connector connection pool by using the
flush-connection-pool
subcommand or theping-connection-pool
subcommand.
To Update a Connector Connection Pool
Use the get
and set
subcommands to view and change the values of the
connector connection pool properties.
-
List the connector connection pools by using the
list-connector-connection-pools
subcommand. -
View the properties of the connector connection pool by using the
get
subcommand. For example:asadmin> get domain.resources.connector-connection-pool.conectionpoolname.*
-
Set the property of the connector connection pool by using the
set
subcommand. For example:asadmin> set domain.resources.connector-connection-pool .conectionpoolname.validate-atmost-once-period-in-seconds=3
-
If needed, restart the server. Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
To Delete a Connector Connection Pool
Use the delete-connector-connection-pool
subcommand in remote mode to
remove a connector connection pool.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the connector connection pools by using the
list-connector-connection-pools
subcommand. -
If necessary, notify users that the connector connection pool is being deleted.
-
Delete the connector connection pool by using the
delete-connector-connection-pool
subcommand.
Example 12-3 Deleting a Connector Connection Pool
This example deletes the connection pool named jms/qConnPool
.
asadmin> delete-connector-connection-pool --cascade=false jms/qConnPool
Command delete-connector-connection-pool executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-connector-connection-pool
at the command
line.
Administering Connector Resources
A connector resource provides an application or module with the means of connecting to an EIS. Typically, you create a connector resource for each EIS that is accessed by the applications deployed in the domain.
The following topics are addressed here:
To Create a Connector Resource
Use the create-connector-resource
subcommand in remote mode to
register a new connector resource with its JNDI name.
Creating a connector resource is a dynamic event and does not require server restart. However, there are some parameters that do require server restart. See Configuration Changes That Require Restart.
Before You Begin
Before creating a connector resource, you must first create a connector connection pool. For instructions, see To Create a Connector Connection Pool.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create the connector resource by using the
create-connector-resource
subcommand.Information about properties for the subcommand is included in this help page.
-
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 12-4 Creating a Connector Resource
This example creates a new resource named jms/qConnFactory
for the
jms/qConnPool
connection pool.
asadmin> create-connector-resource --poolname jms/qConnPool
--description "creating sample connector resource" jms/qConnFactory
Command create-connector-resource executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-connector-resource
at the command line.
To List Connector Resources
Use the list-connector-resources
subcommand in remote mode to list the
connector resources that have been created.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the connector connection pools by using the
list-connector-resources
subcommand.
Example 12-5 Listing Connector Resources
This example lists the existing connector resources.
asadmin> list-connector-resources
jms/qConnFactory
Command list-connector-resources executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-connector-resources
at the command line.
To Update a Connector Resource
Use the get
and set
subcommands to view and change the values of the
connector resource properties.
-
List the connector connection pools by using the
list-connector-resources
subcommand. -
View the properties of the connector resource by using the
get
subcommand. For exampleasadmin> get domain.resources.connector-resource.jms/qConnFactory
-
Set the property of the connector resource by using the
set
subcommand. For example:asadmin> set domain.resources.connector-resource.jms/qConnFactory.enabled=true
-
If needed, restart the server. Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
To Delete a Connector Resource
Use the delete-connector-resource
subcommand in remote mode to remove
a connector resource by specifying the JNDI name.
Before You Begin
Before deleting a resource, all associations with the resource must be removed.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the connector connection pools by using the
list-connector-resources
subcommand. -
If necessary, notify users that the connector resource is being deleted.
-
Delete the connector resource by using the
delete-connector-resource
subcommand.
Example 12-6 Deleting a Connector Resource
This example deletes the jms/qConnFactory
connector resource.
asadmin> delete-connector-resource jms/qConnFactory
Command delete-connector-resources executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-connector-resource
at the command line.
Administering the Resource Adapter Configuration
The following topics are addressed here:
To Create Configuration Information for a Resource Adapter
Use the create-resource-adapter-config
subcommand in remote mode to
create configuration information for a resource adapter, also known as a
connector module. You can run the subcommand before deploying a resource
adapter, so that the configuration information is available at the time
of deployment. The resource adapter configuration can also be created
after the resource adapter is deployed. In this situation, the resource
adapter is restarted with the new configuration.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create configuration information by using the
create-resource-adapter-config
subcommand.Information about properties for the subcommand is included in this help page.
Example 12-7 Creating a Resource Adapter Configuration
This example creates the configuration for resource adapter ra1
.
asadmin> create-resource-adapter-config --property foo=bar
--threadpoolid mycustomerthreadpool ra1
Command create-resource-adapter-config executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-resource-adapter-config
at the command
line.
To List Resource Adapter Configurations
Use the list-resource-adapter-configs
subcommand in remote mode to
list the configuration information contained in the domain configuration
file (domain.xml
) for the specified resource adapter (connector
module).
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the configurations for a resource adapter by using the
list-resource-adapter-configs
subcommand.
Example 12-8 Listing Configurations for a Resource Adapter
This example lists all the resource adapter configurations.
asadmin> list-resource-adapter-configs
ra1
ra2
Command list-resource-adapter-configs executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-resource-adapter-configs
at the command line.
To Update a Resource Adapter Configuration
Use the get
and set
subcommands to view and change the values of the
resource adapter configuration properties.
-
List the configurations for a resource adapter by using the
list-resource-adapter-configs
subcommand. -
View the properties of the connector resource by using the
get
subcommand. For example:asadmin>get domain.resources.resource-adapter-config.ra1.*
-
Set the property of the connector resource by using the
set
subcommand. For example:asadmin> set domain.resources.resource-adapter-config.ra1.raSpecificProperty=value
To Delete a Resource Adapter Configuration
Use the delete-resource-adapter-config
subcommand in remote mode to
delete the configuration information contained in the domain
configuration file (domain.xml
) for a specified resource adapter
(connector module).
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the configurations for a resource adapter by using the
list-resource-adapter-configs
subcommand. -
Delete the configuration for a resource adapter by using the
delete-resource-adapter-config
subcommand.
Example 12-9 Deleting a Resource Adapter Configuration
This example deletes the configuration for resource adapter ra1
.
asadmin> delete-resource-adapter-config ra1
Command delete-resource-adapter-config executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-resource-adapter-config
at the command
line.
Administering Connector Security Maps
The EIS is any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. The connector security map is used to map the application’s credentials to the EIS credentials.
A security map applies to a particular connector connection pool. One or more named security maps can be associated with a connector connection pool.
The following topics are addressed here:
To Create a Connector Security Map
Use the create-connector-security-map
subcommand in remote mode to
create a security map for the specified connector connection pool. If
the security map is not present, a new one is created. You can specify
back-end EIS principals or back-end EIS user groups. The connector
security map configuration supports the use of the wild card asterisk
(*) to indicate all users or all user groups.
You can also use this subcommand to map the caller identity of the application (principal or user group) to a suitable EIS principal in container-managed authentication scenarios.
Before You Begin
For this subcommand to succeed, you must have first created a connector connection pool. For instructions, see To Create a Connector Connection Pool.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create a connector security map by using the
create-connector-security-map
subcommand.Information about the options for the subcommand is included in this help page.
-
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 12-10 Creating a Connector Security Map
This example creates a connector security map securityMap1
for
connection-pool1
.
asadmin> create-connector-security-map --poolname connector-pool1
--principals principal1, principal2 --mappedusername backend-username securityMap1
Command create-connector-security-map executed successfully
To List Connector Security Maps
Use the list-connector-security-maps
subcommand in remote mode to list
the existing security maps belonging to the specified connector
connection pool. You can get a simple listing of the connector security
maps for a connector connection pool, or you can get a more
comprehensive listing that shows the principals of the map.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List existing connector connection pools by using the
list-connector-connection-pools
subcommand. -
List the security maps for a specific connector connection pool by using the
list-connector-security-maps
subcommand.
Example 12-11 Listing All Connector Security Maps for a Connector Connection Pool
This example lists the connector security maps associated with
connector-Pool1
.
asadmin> list-connector-security-maps connector-Pool1
securityMap1
Command list-connector-security-maps executed successfully.
Example 12-12 Listing Principals for a Specific Security Map for a Connector Connection Pool
This example lists the principals associated with securityMap1
.
asadmin> list-connector-security-maps --securitymap securityMap1 connector-Pool1
principal1
principal1
Command list-connector-security-maps executed successfully.
Example 12-13 Listing Principals of All Connector Security Maps for a Connector Connection Pool
This example lists the connector security maps associated with
connector-Pool1
.
asadmin> list-connector-security-maps --verbose connector-Pool1
securityMap1
principal1
principal1
Command list-connector-security-maps executed successfully.
To Update a Connector Security Map
Use the update-connector-security-map
subcommand in remote mode to
create or modify a security map for the specified connector connection
pool.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List existing connector security maps by using the
list-connector-security-maps
subcommand. -
Modify a security map for a specific connector connection pool by using the
update-connector-security-map
subcommand. -
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 12-14 Updating a Connector Security Map
This example adds principals to securityMap1
.
asadmin> update-connector-security-map --poolname connector-pool1
--addprincipals principal1, principal2 securityMap1
Command update-connector-security-map executed successfully.
To Delete a Connector Security Map
Use the delete-connector-security-map
subcommand in remote mode to
delete a security map for the specified connector connection pool.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List existing connector connection pools by using the
list-connector-connection-pools
subcommand. -
Delete a security map for a specific connector connection pool by using the
delete-connector-security-map
subcommand.Information about options for this subcommand is included in this help page.
Example 12-15 Deleting a Connector Security Map
This example deletes securityMap1
from connector-pool1
.
asadmin> delete-connector-security-map --poolname connector-pool1 securityMap1
Command delete-connector-security-map executed successfully
Administering Connector Work Security Maps
The EIS is any system that holds the data of an organization. It can be a mainframe, a messaging system, a database system, or an application. The connector work security map is used to is used to map the EIS credentials to the credentials of Eclipse GlassFish security domain.
A security map applies to a particular connector connection pool. One or more named security maps can be associated with a connector connection pool.
The following topics are addressed here:
To Create a Connector Work Security Map
Use the create-connector-work-security-map
subcommand in remote mode
to map the caller identity of the work submitted by the connector module
(resource adapter) EIS principal or EIS user group to a suitable
principal or user group in the Eclipse GlassFish security domain. One or
more work security maps can be associated with a connector module.
The connector security map configuration supports the use of the wild card asterisk (*) to indicate all users or all user groups.
Before You Begin
Before creating a connector work security map, you must first create a connector connection pool. For instructions, see To Create a Connector Connection Pool.
-
Ensure that the server is running. Remote subcommands require a running server.
-
Create the connector work security map by using the
create-connector-work-security-map
subcommand.Information about properties for the subcommand is included in this help page.
-
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 12-16 Creating Connector Work Security Maps
The following examples create workSecurityMap1
and workSecurityMap2
for my-resource-adapter-name
.
asadmin> create-connector-work-security-map --raname my-resource-adapter-name
--principalsmap eis-principal-1=server-principal-1,eis-principal-2=server-principal-2,
eis-principal-3=server-principal-1 workSecurityMap1
asadmin> create-connector-work-security-map --raname my-resource-adapter-name
--groupsmap eis-group-1=server-group-1,eis-group-2=server-group-2,
eis-group-3=server-group-1 workSecurityMap2
Command create-connector-work-security-map executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-connector-work-security-map
at the command
line.
To List Connector Work Security Maps
Use the list-connector-work-security-maps
subcommand in remote mode to
list the work security maps that belong to a specific connector module.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the connector work security maps by using the
list-connector-work-security-maps
subcommand.
Example 12-17 Listing the Connector Work Security Maps
This example lists the generic work security maps.
asadmin> list-connector-work-security-maps generic-ra
generic-ra-groups-map: EIS group=eis-group, mapped group=glassfish-group
generic-ra-principals-map: EIS principal=eis-bar, mapped principal=bar
generic-ra-principals-map: EIS principal=eis-foo, mapped principal=foo
Command list-connector-work-security-maps executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-connector-work-security-maps
at the command
line.
To Update a Connector Work Security Map
Use the update-connector-work-security-map
subcommand in remote to
modify a work security map that belongs to a specific resource adapter
(connector module).
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the connector work security maps by using the
list-connector-work-security-maps
subcommand. -
If necessary, notify users that the connector work security map is being modified.
-
Update a connector work security map by using the
update-connector-work-security-map
subcommand.
Example 12-18 Updating a Connector Work Security Map
This example removes a principal from a work security map.
asadmin> update-connector-work-security-map --raname generic-ra
--removeprincipals eis-foo generic-ra-principals-map
Command update-connector-work-security-map executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help update-connector-work-security-map
at the command
line.
To Delete a Connector Work Security Map
Use the delete-connector-work-security-map
subcommand in remote mode
to delete a work security map that belongs to a specific connector
module (resource adapter).
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the connector work security maps by using the
list-connector-work-security-maps
subcommand. -
Delete a connector work security map by using the
delete-connector-work-security-map
subcommand.
Example 12-19 Deleting a Connector Work Security Map
This example deletes the worksecuritymap1
map from the my_ra
connector module.
asadmin> delete-connector-work-security-map --raname my_ra worksecuritymap1
Command delete-connector-work-security-map executed successfully.
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help delete-connector-work-security-map
at the command
line.
Administering Administered Objects
Packaged within a connector module, an administered object provides specialized functionality for an application. For example, an administered object might provide access to a parser that is specific to the connector module and its associated EIS.
The following topics are addressed here:
To Create an Administered Object
Use the create-admin-object
subcommand to create an administered
object resource. When creating an administered object resource,
name-value pairs are created, and the object is associated to a JNDI
name.
Before You Begin
The resource adapter must be deployed before running this subcommand
(jmsrar.rar
).
-
Create an administered object by using the
create-admin-object
subcommand.Information about properties for the subcommand is included in this help page.
-
If needed, restart the server.
Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
Example 12-20 Creating an Administered Object
For this example, the jakarta.jms.Queue
resource type is obtained from
the ra.xml
file. The JNDI name of the new administered object is
jms/samplequeue
.
asadmin> create-admin-object --restype jakarta.jms.Queue --raname jmsra
--description "sample administered object" --property Name=sample_jmsqueue jms/samplequeue
Command create-admin-object executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help create-admin-object
at the command line.
To List Administered Objects
Use the list-admin-object
subcommand in remote mode to list the
existing administered objects.
-
Ensure that the server is running. Remote subcommands require a running server.
-
List the administered objects by using the
list-admin-objects
subcommand.
Example 12-21 Listing Administered Objects
This example lists the existing administered objects.
asadmin> list-admin-objects
jms/samplequeue
Command list-admin-objects executed successfully
See Also
You can also view the full syntax and options of the subcommand by
typing asadmin help list-admin-object
at the command line.
To Update an Administered Object
Use the get
and set
subcommands to view and change the values of the
administered objects properties.
-
List the administered objects by using the
list-admin-objects
subcommand. -
View the properties of the administered object by using the
get
subcommand. For example:asadmin> get domain.resources.admin-object-resource.jms/samplequeue.*
-
Set the property of the administered object by using the
set
subcommand. For example:asadmin> set domain.resources.admin-object-resource.jms/samplequeue.enabled=false
-
If needed, restart the server. Some properties require server restart. See Configuration Changes That Require Restart. If your server needs to be restarted, see To Restart a Domain.
To Delete an Administered Object
Use the delete-admin-object
subcommand to delete an administered objects.
-
List the administered objects by using the
list-admin-objects
subcommand. -
If necessary, notify users that the administered object is being deleted.
-
Delete an administered object by using the
delete-admin-object
subcommand.
Example 12-22 Deleting an Administered Object
This example deletes the administered obje