Copyright © 2008-2009 OW2 Consortium
This work is licensed under the Creative Commons Attribution-ShareAlike License. To view a copy of this license,visit http://creativecommons.org/licenses/by-sa/2.0/deed.en or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
A server, or JOnAS instance, is a java process started via the jonas start command, or via the administration tool Java EE.
Several servers may run on the same physical host.
When a server starts, services are started.
A service typically provides system resources to containers. Most of the components of the JOnAS application server are pre-defined services. However, it is possible and easy for an advanced user to define a new service and to integrate it into JOnAS.
A container consists of a set of Java classes that implement the Java EE specification. The role of the container is to provide the facilities for executing Java EE components.
There are three types of containers:
EJB container in which Enterprise JavaBeans are deployed and run
Web container for JSPs and servlets
A domain represents an administration perimeter which is under the control of an administration authority.
This perimeter contains management targets like servers and clusters.
If a domain contains several elements, it provides at least one common administration point represented by a master server.
A master is a JOnAS instance having particular management capabilities within the domain:
it is aware of the domain's topology
it allows management and monitoring of all the elements belonging to the domain
A cluster is a group of JOnAS servers having common properties within a domain. It usually allows to run a J2EE application, or a J2EE module, on the cluster members as if they were a single server. The objective is to achieve applications scalability and high availability.
JOnAS supports several cluster types:
Clusters for Web level load-balancing
Clusters for high availability of Web components
Clusters for EJB level load-balancing
Clusters for high availability of EJB components
Clusters for JMS destination scalability and high availability
Clusters for administration purpose which facilitate management operations like deployment /undeployment.
From the administrator point of view, a cluster represents a single administration target.
Note that a particular JOnAS server may belong to zero, one or more clusters.
This section presents the possible targets of a JOnAS administrator. An administrator may act on the following targets:
An individual JOnAS server.
A management domain.
A management cluster.
The servers composing a management domain can be grouped into one ore more clusters. These are clustered servers. A domain may have clustered and un-clustered servers.
Each target is identified by a unique name.
A JOnAS server name is given by the value of the
option used in the
jonas start command (the default name is
The domain name is given by the value of the
domain.name environment variable (by default, a server is
started in a domain having the server's name). See How to configure a domain
for more details.
The naming of the clusters depend on configuration parameters which are different for the different cluster types.
This section presents the means offered to a JOnAS administrator to act on an administration target:
The JOnAS commands, particulary the jonas admin command.
Management applications deployed on a JOnAS server. This may by the JonasAdmin web application, or any custom J2EE management application based on the Section 3.1, “Management EJB Component”.
Any generic JMX management console connected to a target server via a JMX Remote Connector Section 4.1, “JSR 160 support in JOnAS”.
WebService clients using the WebService end-point exposed by the Management EJB
Other mechanisms like ant tasks.
This section presents the operations provided to the JOnAS administrator.
These operations depend on the management target.
JOnAS administration mainly provides monitoring and configuration functions. Moreover, administrator can dynamically install/deploy/undeploy applications and/or resources on a running server.
All the functions are proposed by the JonasAdmin application, wereas the jonas admin command supports only a part of these functions.
Domain administration is mainly based on JonasAdmin.
It allows consulting the domain map (shows the servers and clusters in the domain) and modify this map.
Moreover, monitoring of the domain is provided: shows state evolution of servers and clusters, and statistics on resources used by the different servers in the domain.
Finally, dynamic install/deploy/undeploy operations are extended at the domain level: the applications source is the administaror server and operation's target may be one ore more servers and/or clusters in the domain.
JonasAdmin is an administration tool providing a user friendly graphical console.
JonasAdmin was developed using the Struts framework; it uses standard technologies such as Java Servlets and JavaServer Pages and JMX.
As with any web application, JonasAdmin requires a servlet server to be installed.
Make sure that the
web service is listed in the
Designed as a web application, JonasAdmin is packed in a WAR and installed under the
Once the server started, JonasAdmin is automatically deployed if the depmonitor service is activated. Otherwise, JonasAdmin can be deployed manually using the jonas admin command.
When accessing JonasAdmin, the administrator must provide identification and authentication.
configuration file contains a memory realm definition named
, which is referenced in both
(for Tomcat) and
(for Jetty) configuration files. The default user name (
) and password (
) corresponding to the
role can be modified here.
Once started, JonasAdmin can administer the JOnAS server in which it is running. If the host server is a master, JonasAdmin can also administer the rest of the servers running in the domain.
Once the JonasAdmin application deployed on a server, the
administration console is accessible at the URL:
http://<hostname>:<portnumber>/jonasAdmin/ using any web
<hostname> is the name of the host where the Servlet container is running and <portnumber> is the http port number (default is 9000).
After logging in, the left-hand frame in the Welcome page displays
the management tree associated with the JOnAS server running JonasAdmin.
The management tree's root is
Domain , which allows to the
domain management facilities in case of a master server.
In the image below, JonasAdmin is running on the master server named
jonas within a domain also named
jonas. It is immediately apparent that
this is a master server, as we have a
Monitoring and a
Domain root node.
The management tree in this figure allows access to the following main management facilities:
Domain administration with domain level deployment facilities.
Current server administration
Communication protocols management
Active services presentation and configuration
Dynamic deployment at the current server level
Joram platform administration
Displays general information about the administered JOnAS server, including the JMX server and the WEB server, and provides the capability of listing the content of the Registry.
Presents memory usage, a count of the threads created by JOnAS, and other monitoring information concerning managed services and resources.
Allows the administrator to configure the JOnAS Logging system. Additionally, if Tomcat is used as the WEB container service implementation, it allows creation of new access log valves.
This management facility relates to the integration of Tomcat
management in JonasAdmin. It currently presents connectors defined in
the Tomcat configuration and allows for the creation of new HTTP, HTTPS,
or AJP connectors. Note that the
Protocols sub-tree is
not presented if Jetty is used as the WEB container service
All the active services have a corresponding sub-tree in the
Managing the various container services consists of presenting information about the components deployed in these containers. New components can be deployed using the dynamic deployment facilities presented in the next section.
Similarly, the services that allow management of the different
types of resources (DataSources, Resource Adapters and Mail resources)
also provide information about the resources being deployed.
Additionally, deployed resources (DataSources or MailFactories) can be
reconfigured and their new configuration made persistent by using a
The transaction service management allows reconfiguration (possibly persistent) and presents monitoring information about transactions managed by JOnAS.
A very useful management operation is the capability of installing
(upload), deploying, undeploying or removeing stand-alone J2EE
components (JAR, WAR, RAR packages) or J2EE applications (EAR packages)
in the administered server using the
The administrator's task is facilitated by the display of the list
of deployable modules, the list of deployed modules, and the capability
of transferring modules from one list to another (which corresponds to
The deployable modules can be installed in directories specific to
their type, for example, the deployable JARs are un-deployed JARs
JONAS_BASE/ejbjars/ directory, or in the
Deployment sub-tree also allows a J2EE package
to be uploaded from the local file system to the corresponding directory
of the administered server (
install operation), and the
Resources sub-tree provides the capability of
loading or creating new resources managed by the active services.
It is important to note that JOnAS and Tomcat have different
approaches to reconfiguration persistency. In JOnAS, every
Save operation is related to a service or a resource
reconfiguration. For example, the administrator can reconfigure a service
and a resource, but choose to save only the new resource configuration. In
Save operation is global to all configuration
changes that have been performed. For example, if a new HTTP connector is
reconfigured and a new context created for a web application, both
configuration changes are saved when using the
First recall that domain management functions are accessible only
when JonasAdmin is deployed on a master server. The
tree contains only one
Server sub-tree, the currently
administered server, which is initially the server hosting
Domain management principal function is to present the domain topology: list all the servers and clusters belonging to the domain. It also allows modification of the domain topology by adding new servers and clusters to the domain, removing servers and moving servers to/from clusters.
The domain management page also presents servers that are not yet
started but are specified as belonging to the domain in the new
configuration file named
domain.xml . Also, a server can be
added to the domain when it has been started without having the discovery
An essential domain management function is that the administrator
can switch from the master to any of the other servers in the domain.
Currently, JonasAdmin allows only one category of global domain level
management operation, the
deployment operation. Using any
other management operation requires switching to the server to be
Domain level deployment allows for
deploying one or
more J2EE packages (JARs, WARs, RARs or EARs), which are installed in the
corresponding master directory (ejbjars, webaps, rars or apps), into any
running server in the domain. A
deployment operation target
may be a server but also a cluster. The
may have three semantics:
deploy only (create container) - which is useful when the package is already installed on the target server.
distribute only - which means install the package in the target's corresponding directory
distribute and (re)deploy the package, with optionally replacing the current package with the new one.
Note that at domain level deployment the
Remove operations are only related to the master server
The MEJB is specified by the J2EE Management Specification which defines the J2EE Management Model.
The MEJB component exposes the managed objects within the JOnAS platform as JMX manageable resources (MBeans). It is packed in an ejb-jar file installed in the JONAS_ROOT/deploy directory, and therefore it can be loaded at server start-up.
The MEJB component is registered in JNDI under the name
Access to the MEJB provided by the JOnAS 5 distribution is now role secured. The client application that wants to access it must have one of the following roles:
for accessing to the read-only operation of the MEJB
role allowing access for all operation of the MEJB
Unauthorized access is forbidden
This snippet includes all of the elements needed to specify
security roles in the
web.xml file of a web application client of
<security-constraint> <web-resource-collection> <web-resource-name>Protected Area</web-resource-name> <!-- Define the context-relative URL(s) to be protected --> <url-pattern>/*</url-pattern> <!-- If you list http methods, only those methods are protected --> <http-method>DELETE</http-method> <http-method>GET</http-method> <http-method>POST</http-method> <http-method>PUT</http-method> </web-resource-collection> <auth-constraint> <!-- Anyone with one of the listed roles may access this area --> <role-name>mejb-admin</role-name> </auth-constraint> </security-constraint> <!-- Default login configuration uses BASIC authentication --> <login-config> <auth-method>BASIC</auth-method> <realm-name>JOnAS Realm</realm-name> </login-config> <!-- Security roles referenced by this web application --> <security-role> <role-name>mejb-admin</role-name> </security-role>
JOnAS administration is based on the standard MBeans defined by the J2EE Management Specification, and on more MBeans provided by JOnAS itself and by components integrated integrated in JOnAS: Tomcat/Jetty server, JORAM platform, JMX Server, etc.
All the MBeans defined by the J2EE Management Specification are provided by JOnAS. These MBeans respect the naming conventions and are registered in the JMX server embeded in any JOnAS instance.
The J2EEServer MBean provides attributes and methods for the server management. For example, it supports resource and application deployment. It also provides server configuration and monitoring information.
The aim of JOnAS thread dump feature is to provide an access to a thread stack dump from the underlying JVM of a running JOnAS server for monitoring purpose. The thread dump access is done through a JMX connection to the JOnAS "J2EEServer" MBean (named such as "$domainname:j2eeType=J2EEServer,name=$jonasname" depending on the JOnAS domain and server name). This feature gathers few operations directly available on JOnAS server through a JMX connection to the "J2EEServer" MBean " or through a Flex visualization module integrated in the web-based JonasAdmin application.
A set of operations is available on the remote server, it can be accessed by any JMX client connecting to the JOnAS J2EEServer Mbean. Here is a list of the available operations with an example using the JConsole:
This operation gives the JVM thread stack dump as a string. The result of this operation is the same as reading the attribute threadStackDump.
This operation logs the JVM thread stack dump in JOnAS log file (level:info).
This operation prints the JVM thread stack dump in a given file on the remote server.
This operation gives the JVM thread stack dump as a TabularData object. The composition of the returned object is a set of properties-values elements, each element representing a givean thread. Thus, such a structured object can be easily used in a script.
For instance, the above operations can be easily tried using the JConsole diplaying the following interface:
Here is a result of the getThreadStackDumpList operation given by the JConsole. Navigation between elements is done using right and left arrows, each thread properties are displayed.
Please note all the above operations are also available through the MBeanCmd Dump Command
JonasAdmin web application provides a Flex module that lets you view all threads information. This module is available in the "Monitoring" node from the "Server JOnAS" section by clicking on the "StackDump" tab.
If JOnAs is started as a master ("jonas.master" property in the "jonas.properties" file is set to "true"), the thread stack dump visualization module is available for the current administrated server. Thus a master can access the thread stack dump of any server from the same domain through jonasAdmin stackDump visualization module by switching the current administrated server.
The visualization module shows all threads name and id from the JVM. Threads can be ordered by names or ids by clicking on the header of the related column. A selection of one or more threads can be done by clicking on names or ids. Selected threads information such as priority, state or stacktrace appear in a column to the right.
The Refresh button refreshes the threads list from the underlying JVM.
The Select all button allows to select all the threads from the JVM to get the complete "stacktrace" information from the server.
The Copy to clipboard button allows to copy all selected threads information in the clipboard so they could be pasted in a file to be kept. (Please also note that any part from the right column can be selected using the mouse and copied with a right click).
JOnAS provides support for remote connection to the MBean server in a standard way based on the JMX Remote API.
The JSR 160 specifies the JMX Remote API which extends the JMX specification by providing a standard way to connect to remote JMX-enabled applications.
Currently, JSR 160 has defined a mandatory connector based on RMI (that supports both RMI/JRMP and RMI/IIOP).
JSR 160 support implies providing standard connector server objects.
The JMX service creates at start-up one or several such objects, depending
on the protocols configuration (defined in
carol.properties file). To create a client connector, the
client side needs to know the URL of the connector server. Below we
present the URLs that can be used by the clients depending on the protocol
Currently only 2 protocols can be used by JSR-160 connectors: RMI/JRMP and RMI/IIOP.
This connector can be used if the
is set in the
The client has
to construct a
JMXServiceURL using the following
String , possibly modified according to the JOnAS-specific
host is the host on which is running the
JOnAS server to be managed. The
port number is given in the
JMXConnector has to be created and connected to the connector
server using the JMX Remote API.
Hashtable environment = null; JMXServiceURL address = new JMXServiceURL("service:jmx:rmi:///jndi/rmi://host:1099/jrmpconnector_jonas"); JMXConnector connector = JMXConnectorFactory.newJMXConnector(address, environment); connector.connect(environment);
This connector can be used if the
is set in the
The client code
is similar to the JRMP case, but the
String to be used to
JMXServiceURL must adhere to the following