<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:lang="en" xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:mml="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <info>
    <title>JOnAS thread dump feature</title>
  </info>

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

  <section>
    <info>
      <title>Available operations</title>
    </info>

    <para>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:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis role="bold">getThreadStackDump</emphasis></para>

        <para>This operation gives the JVM thread stack dump as a string. The
        result of this operation is the same as reading the attribute
        <emphasis role="bold">threadStackDump</emphasis>.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">logThreadStackDump</emphasis></para>

        <para>This operation logs the JVM thread stack dump in JOnAS log file
        (level:info).</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">printThreadStackDump</emphasis></para>

        <para>This operation prints the JVM thread stack dump in a given file
        on the remote server.</para>
      </listitem>

      <listitem>
        <para><emphasis role="bold">getThreadStackDumpList</emphasis></para>

        <para>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.</para>
      </listitem>
    </itemizedlist>

    <para>For instance, the above operations can be easily tried using the
    JConsole diplaying the following interface:</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="../../../resources/images/jconsoleStackDumpOperations.png">
          <info>
            <othercredit class="other" otherclass="srccredit">
              <orgname>???</orgname>

              <contrib>JonasAdmin</contrib>
            </othercredit>
          </info>
        </imagedata>
      </imageobject>
    </mediaobject>

    <para>Here is a result of the <emphasis
    role="bold">getThreadStackDumpList</emphasis> operation given by the
    JConsole. Navigation between elements is done using right and left arrows,
    each thread properties are displayed.</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="../../../resources/images/jconsoleStackDumpList.png">
          <info>
            <othercredit class="other" otherclass="srccredit">
              <orgname>???</orgname>

              <contrib>JonasAdmin</contrib>
            </othercredit>
          </info>
        </imagedata>
      </imageobject>
    </mediaobject>

    <para>Please note all the above operations are also available through the
    <link xlink:href="http://jasmine.ow2.org/doc/current/mbeancmd_guide/index.php">MBeanCmd</link>
    Dump Command</para>
  </section>

  <section>
    <info>
      <title>JonasAdmin visualization module</title>
    </info>

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

    <mediaobject>
      <imageobject>
        <imagedata fileref="../../../resources/images/jonasAdminStackDump.png">
          <info>
            <othercredit class="other" otherclass="srccredit">
              <orgname>???</orgname>

              <contrib>JonasAdmin</contrib>
            </othercredit>
          </info>
        </imagedata>
      </imageobject>
    </mediaobject>

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

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

	<para>The <emphasis role="bold">Refresh</emphasis> button refreshes the
    threads list from the underlying JVM.</para>

    <para>The <emphasis role="bold">Select all</emphasis> button allows to
    select all the threads from the JVM to get the complete "stacktrace"
    information from the server.</para>

	<para>The <emphasis role="bold">Copy to clipboard</emphasis> 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).</para>
  </section>
</section>