# 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: architecture@objectweb.org

    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>