About the Thread Management Framework

ThreadManagementFramework is a tool for the control of threads created by an application. It can ensure that, during the entire life cycle of the application, never more than X threads will run at the same time. The organization for managing threads inside the framework can be represented by a graph of areas, as described below.

Users can configure this graph according to their needs via an XML file. For example, the XML declaration for the graph above is :

<!DOCTYPE area PUBLIC "-//objectweb.org//DTD ObjectWeb Area Management 1.0//EN" "ow_area.dtd">

<area name="OTM" description="ObjectWeb Thread Management" limit="200">

    <alarm class="org.objectweb.area.lib.DefaultAlarm"/> <!-- Alarm2 -->

    <area name="java" description="Java packages" limit="100">
        <alarm class="org.objectweb.area.lib.OutOfMemoryAlarm"/> <!-- Alarm1 -->
        <java package="java."/>
        <java package="javax."/>
        <java package="sun."/>
    </area>

    <area name="OW packages"	description="ObjectWeb packages" limit="100">
        <java package="org.objectweb."/>
    </area>

    <area name="local" description="Local packages" limit="100">
        <java package=""/>
    </area>

</area>
      

Areas have been defined for managing a group of resources, in this case threads. Thus, management of every Area can be separate, with a specific behaviour associated to each one. As illustrated in the figure above, an area is a node of the graph. Therefore, each area has a parent (except for the root area), can have a limit, and can trigger an alarm (also represented in the graph) when the limit is reached.

Each area is dedicated to accept threads, according to a specific criteria, like the package in which the threads are created. When a thread enters an area, it enters in the parent area also. Thus, the root area (at the top of the graph) counts all the threads created by the application.

To ensure this property, the Thread class is modified via ASM for entering an Area before start, and exiting the Area after exit.

Table of Contents

1. Integration of TMF in JOnAS
   • Configuration
   • Management
2. Build and Use Thread Management Framework
• Generate the Distribution Version
• How TMF Works
• Libraries Organization
• Using TMF on the Examples

1. Integration of TMF in JOnAS

With TMF, it is possible to control all the threads that are created inside JOnAS. Specifically, the property that specifies that an EJB is not allowed to create threads is ensured by assigning a specific Area for EJBs, with 0 for the limit.

Configuration

To use TMF with JOnAS:

• Enable the framework with the controlTMF script :

          shell> controlTMF enable
	

This activation will proceed as follows:

1. Execution of the AdaptThreadClass to rewrite the java.lang.Thread class. (or ThreadGroup, for IBM JVM, see the Note)
2. Generation of the ow_thread.jar & ow_area.jar in the lib/endorsed JOnAS directory.
3. Copy the ow_jonas_thread.jar in the lib/commons/jonas directory, for MBean management.

• Edit jonas.properties, to define a new service, started just after the jmx service:

#  Set the list of the services launched in the JOnAS Server.
#  Possible services are: registry,jmx,security,jtm,db,mail,dbm,resource,jms,ejb,ws,web,ear,discovery.
#  registry,jmx,jtm,ejb are mandatory.
#  (registry and jmx are automatically started even if not present in the list)
#  Order in the list is important (see 'Configuring JOnAS services' in JOnAS documentation)
#
jonas.services    registry,jmx,thread,jtm,security,resource,ejb,ws,web,ear
...
###################### JOnAS Thread
#
#
jonas.service.thread.class       org.objectweb.area.jonas.AreaService
jonas.service.thread.file        jonas_areas.xml
jonas.service.thread.ejbareaname EJB
	

• Edit the area XML configuration file in $JONAS_ROOT/conf directory, according to your configuration.

Then, start JOnAS and the Thead management will be activated.

Note: To disable TMF, run controlTMF disable and remove the thread service defined in jonas.properties.

A more complex configuration for the jonas_areas.xml graph could be :

whose definition is:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!--
====================================================================

ObjectWeb Area Management Framework
Copyright (C) 2005 INRIA - Jacquard Team
Contact: [email protected]

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307
USA

Initial developer(s): Philippe Merle.
Contributor(s): Nicolas Dolet.

For the configuration of the ObjectWeb Area Management Framework.

====================================================================
-->

<!DOCTYPE area
          PUBLIC "-//objectweb.org//DTD ObjectWeb Area Management 1.0//EN"
          "ow_area.dtd">

<area name="jonas_areas" description="ObjectWeb Thread Management" class="org.objectweb.area.lib.NoLockArea" limit="500">

  <area name="rmi" description="Java RMI" class="org.objectweb.area.lib.NoLockArea" limit="100">

    <alarm class="org.objectweb.area.jonas.LogAlarm"/>

    <java package="java.rmi."/>
    <java package="javax.rmi."/>
    <java package="sun.rmi."/>
    <java package="javax.management.remote.rmi."/>
    <java package="org.omg.stub.java.rmi."/>
  </area>

  <area name="jmx" description="Java JMX" class="org.objectweb.area.lib.NoLockArea" limit="100">
    <java package="javax.management.remote."/>
  </area>

  <area name="resource" description="Resource service (JCA)" class="org.objectweb.area.lib.NoLockArea" limit="100">
    <java package="org.objectweb.jonas.resource."/>
  </area>

  <area name="logger" description="Logger" class="org.objectweb.area.lib.NoLockArea" limit="10">
    <java package="java.util.logging.LogManager."/>
  </area>

  <area name="timer" description="Timer service" class="org.objectweb.area.lib.NoLockArea" limit="100">
    <java package="org.objectweb.jonas_timer."/>
    </area>

  <area name="webserver" description="Web server packages" class="org.objectweb.area.lib.NoLockArea" limit="100">
    <java package="org.objectweb.jonas.web."/>
  </area>

  <area name="JMS-Joram" description="JMS and Joram packages" class="org.objectweb.area.lib.NoLockArea" limit="100">
    <java package="javax.jms."/>
    <java package="org.objectweb.joram."/>
    <java package="fr.dyade.aaa."/>
  </area>

  <area name="transaction" description="Transactions" class="org.objectweb.area.lib.NoLockArea" limit="100">
    <java package="org.objectweb.jotm."/>
    <java package="org.objectweb.transaction.jta."/>
  </area>

  <area name="DBConnection" description="Database connections" class="org.objectweb.area.lib.NoLockArea" limit="100">

    <area name="JavaDbConnection" description="DB connections for java packages" class="org.objectweb.area.lib.NoLockArea" limit="70">
      <java package="java.sql."/>
      <java package="javax.sql."/>
    </area>

    <area name="OWDbConnection" description="DB connections for objectweb packages" class="org.objectweb.area.lib.NoLockArea" limit="70">
      <java package="org.objectweb.jonas.jdbc."/>
      <java package="org.objectweb.jonas.dbm."/>
    </area>

    <area name="HSQL" description="HSQL database embedded in JOnAS" class="org.objectweb.area.lib.NoLockArea" limit="50">
      <java package="org.hsqldb."/>
    </area>

  </area>

  <area name="EJB" description="EJB" limit="0"/>

</area>
	

In this configuration, only one alarm is defined (LogAlarm), in the RMI Area. It will be the default alarm for all areas in the graph. If there is no alarm defined for an area, the default alarm will be searched in the parent area, recursively.

Management

When JOnAS is started, MBeans can be visualized via the jonasAdmin interface, and managed via jconsole.

jonasAdmin

The new thread service is defined on a domain named AreaService and AreaMBeans is registered on the jonas domain. All of these services are available from jonasAdmin: http://hostname:9000/jonasAdmin.

jconsole

The jconsole provides MBeans management services via JMX. The connection is available in the 'advanced' tab.
If the default Carol configuration is used, the connection is established via the jrmp protocol, with the following JMX URL: service:jmx:rmi:///jndi/rmi://hostname:1099/jrmpconnector_jonas.

Local Management with jconsole

Another way to manage the JVM with jconsole is via local management. To enable local management, the application must be launched with -Dcom.sun.management.jmxremote as the JVM parameter. To use it with JOnAS, this argument must be added in the $JONAS_OPTS variable. Then, the other tabs of the jconsole (Summary, Memory, Threads, ...) will be available.

Sample Scenario

For testing the thread control, an EJB that only creates and runs a thread can be deployed.
As the limit of the EJB area is null, the thread will be blocked. It can be unblocked by changing the limit of the Area, if the time-out has not elapsed.

2. Build and Use Thread Management Framework

Generate the Distribution Version

The framework can be downloaded at http://gforge.inria.fr/projects/tmf.

The mode used for building TMF (Object Oriented, or Component Oriented) can be selected in the etc/build.properties file (default mode is Object Oriented). The Component Oriented mode uses the Fractal Component Model, with the Julia implementation.

Call the dist target with ant:

          shell> ant dist
	

How TMF works

The core of TMF is the adapted java.lang.Thread class. Before launching an application with TMF, make sure that the java.lang.Thread class has been adapted for the correct JVM version. To rewrite this class, run org.objectweb.area.thread.AdaptThreadClass. However, this task is completed during the genereation of the distribution version of TMF.

NOTE: When using the IBM JVM, the Thread class cannot be adapted in the same way. The adapted class is ThreadGroup, the entry in the Area is made during ThreadGroup.add(Thread), and the exit of the Area is made during ThreadGroup.remove(Thread).

Libraries Organization

TMF is encapsulated in two libraries: ow_thread.jar and ow_area.jar..

A third library is used for defining a new service (cf jonas.properties): ow_jonas_thread.jar.

• ow_thread.jar: contains the adapted Thread class and its manager: ThreadManager
• ow_area.jar: contains the API and implementation of TMF (AreaProvider, Area, Alarm...)

Using TMF on the Examples

Go to the 'dist' directory:

          shell> cd dist
	

Four examples are available. For each one, there are three modes of execution (loaded in sequence) :

• Without TMF
• With TMF, using the DefaultAreaProvider
• With TMF, using a specific user AreaProvider. (Note that in these examples, the user's AreaProvider is a singleton and does not search the package in which the Thread is started, thus the overhead is minimal.)

'bench'

Make a bench, i.e., create threads and calculate the execution time.

'queens'

Calculate the solutions of the Queens puzzle problem for chessboards with dimensions from 1*1 to 10*10, and calculate the execution time.

'rmi'

Create threads with the client and use an RMI interface to display a message referring to threads on the server.

'thread'

Create threads in a loop, until the user stops the program (Ctrl^C).

An example:

To use TMF with another example, give the JVM the location of the jars for loading the new Thread class (not the standard Thread class in rt.jar).

• In a shell

  :

            java -Djava.endorsed.dirs={libDirectory} YourMain
  	

• With ant:

            <java classname="YourMain" classpath="...">
                <sysproperty key="java.endorsed.dirs" value="{libDirectory}"/>
            </java>