2006-06-26 Andrew John Hughes <gnu_andrew@member.fsf.org>

	* java/lang/Thread.java:
	(getState()): New method.
	* java/lang/management/ClassLoadingMXBean.java:
	Corrected class documentation.
	* java/lang/management/ManagementFactory.java:
	Added new temporary marked stub to get thread bean.
	* java/lang/management/OperatingSystemMXBean.java:
	Corrected class documentation.
	* java/lang/management/RuntimeMXBean.java:
	Corrected class documentation.
	* java/lang/management/ThreadInfo.java,
	* java/lang/management/ThreadMXBean.java:
	New classes.
	* vm/reference/java/lang/VMThread.java:
	(getState()): New method.
	* vm/reference/java/lang/management/VMThreadInfo.java:
	New VM class.

7 files changed, 935 insertions, 4 deletions

diff --git a/java/lang/Thread.java b/java/lang/Thread.java
index 74d24633b..df4c65ece 100644
--- a/java/lang/Thread.java
+++ b/java/lang/Thread.java
@@ -1221,4 +1221,18 @@ public class Thread implements Runnable
      */
     void uncaughtException(Thread thr, Throwable exc);
   }
+
+  /**
+   * Returns the current state of the thread.  This
+   * is designed for monitoring thread behaviour, rather
+   * than for synchronization control.
+   *
+   * @return the current thread state.
+   */
+  public String getState()
+  {
+    VMThread t = vmThread;
+    return t == null ? null : t.getState();
+  }
+
 }
diff --git a/java/lang/management/ClassLoadingMXBean.java b/java/lang/management/ClassLoadingMXBean.java
index e11c9bb60..2a8651b9c 100644
--- a/java/lang/management/ClassLoadingMXBean.java
+++ b/java/lang/management/ClassLoadingMXBean.java
@@ -40,7 +40,7 @@ package java.lang.management;
 /**
  * Provides access to information about the class loading 
  * behaviour of the current invocation of the virtual
- * machine.  Instances of this bean are obtained by calling
+ * machine.  An instance of this bean is obtained by calling
  * {@link ManagementFactory#getClassLoadingMXBean()}.
  *
  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
diff --git a/java/lang/management/ManagementFactory.java b/java/lang/management/ManagementFactory.java
index a5a2d6acf..5f99bbe1d 100644
--- a/java/lang/management/ManagementFactory.java
+++ b/java/lang/management/ManagementFactory.java
@@ -37,6 +37,8 @@ exception statement from your version. */
 
 package java.lang.management;
 
+import gnu.classpath.NotImplementedException;
+
 import gnu.java.lang.management.ClassLoadingMXBeanImpl;
 import gnu.java.lang.management.OperatingSystemMXBeanImpl;
 import gnu.java.lang.management.RuntimeMXBeanImpl;
@@ -122,5 +124,18 @@ public class ManagementFactory
       classLoadingBean = new ClassLoadingMXBeanImpl();
     return classLoadingBean;
   }
-  
+
+  /**
+   * Returns the thread management bean for the running
+   * virtual machine.
+   *
+   * @return an instance of {@link ThreadMXBean} for
+   *         this virtual machine.
+   */
+  public static ThreadMXBean getThreadMXBean()
+    throws NotImplementedException
+  {
+    return null;
+  }
+
 }
diff --git a/java/lang/management/OperatingSystemMXBean.java b/java/lang/management/OperatingSystemMXBean.java
index 74b9ae5a1..2430a9fbf 100644
--- a/java/lang/management/OperatingSystemMXBean.java
+++ b/java/lang/management/OperatingSystemMXBean.java
@@ -39,7 +39,7 @@ package java.lang.management;
 
 /**
  * Provides access to information about the underlying operating
- * system.  Instances of this bean are obtained by calling
+ * system.  An instance of this bean is obtained by calling
  * {@link ManagementFactory#getOperatingSystemMXBean()}.
  *
  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
diff --git a/java/lang/management/RuntimeMXBean.java b/java/lang/management/RuntimeMXBean.java
index 1aab6bb09..cee1d805f 100644
--- a/java/lang/management/RuntimeMXBean.java
+++ b/java/lang/management/RuntimeMXBean.java
@@ -42,7 +42,7 @@ import java.util.Map;
 
 /**
  * Provides access to information about the underlying virtual
- * machine.  Instances of this bean are obtained by calling
+ * machine.  An instance of this bean is obtained by calling
  * {@link ManagementFactory#getRuntimeMXBean()}.
  *
  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
diff --git a/java/lang/management/ThreadInfo.java b/java/lang/management/ThreadInfo.java
new file mode 100644
index 000000000..a5555cbe6
--- /dev/null
+++ b/java/lang/management/ThreadInfo.java
@@ -0,0 +1,405 @@
+/* ThreadInfo.java - Information on a thread
+   Copyright (C) 2006 Free Software Foundation
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath 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
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package java.lang.management;
+
+/**
+ * <p>
+ * A class which maintains information about a particular
+ * thread.  This information includes:
+ * </p>
+ * <ul>
+ * <li><strong>General Thread Information:</strong>
+ * <ul>
+ * <li>The identifier of the thread.</li>
+ * <li>The name of the thread.</li>
+ * </ul>
+ * </li>
+ * <li><strong>Execution Information:</strong>
+ * <ul>
+ * <li>The current state of the thread (e.g. blocked, runnable)</li>
+ * <li>The object upon which the thread is blocked, either because
+ * the thread is waiting to obtain the monitor of that object to enter
+ * one of its synchronized monitor, or because
+ * {@link java.lang.Object#wait()} has been called while the thread
+ * was within a method of that object.</li>
+ * <li>The thread identifier of the current thread holding an object's
+ * monitor, upon which the thread described here is blocked.</li>
+ * <li>The stack trace of the thread (if requested on creation
+ * of this object</li>
+ * </ul>
+ * <li><strong>Synchronization Statistics</strong>
+ * <ul>
+ * <li>The number of times the thread has been blocked waiting for
+ * an object's monitor or in a {@link java.lang.Object#wait()} call.</li>
+ * <li>The accumulated time the thread has been blocked waiting for
+ * an object's monitor on in a {@link java.lang.Object#wait()} call.
+ * The availability of these statistics depends on the virtual machine's
+ * support for thread contention monitoring (see
+ * {@link ThreadMXBean#isThreadContentionMonitoringSupported()}.</li>
+ * </ul>
+ * </li>
+ * </ul>
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.5
+ * @see ThreadMXBean#isThreadContentionMonitoringSupported()
+ */
+public class ThreadInfo
+{
+
+  /**
+   * The thread which this instance concerns.
+   */
+  private Thread thread;
+
+  /**
+   * The maximum depth of the stack traces for this thread.
+   */
+  private int maxDepth;
+
+  /**
+   * Cache a local reference to the thread management bean.
+   */
+  private static ThreadMXBean bean = null;
+
+  /**
+   * Constructs a new {@link ThreadInfo} corresponding
+   * to the thread specified.
+   *
+   * @param thread the thread on which the new instance
+   *               will be based.
+   */
+  ThreadInfo(Thread thread, int maxDepth)
+  {
+    this.thread = thread;
+    this.maxDepth = maxDepth;
+  }
+
+  /**
+   * Returns the number of times this thread has been
+   * in the {@link java.lang.Thread.State#BLOCKED} state.
+   * A thread enters this state when it is waiting to
+   * obtain an object's monitor.  This may occur either
+   * on entering a synchronized method for the first time,
+   * or on re-entering it following a call to
+   * {@link java.lang.Object#wait()}.
+   *
+   * @return the number of times this thread has been blocked.
+   */
+  public long getBlockedCount()
+  {
+    return VMThreadInfo.getBlockedCount(thread);
+  }
+
+  /**
+   * <p>
+   * Returns the accumulated number of milliseconds this
+   * thread has been in the
+   * {@link java.lang.Thread.State#BLOCKED} state
+   * since thread contention monitoring was last enabled.
+   * A thread enters this state when it is waiting to
+   * obtain an object's monitor.  This may occur either
+   * on entering a synchronized method for the first time,
+   * or on re-entering it following a call to
+   * {@link java.lang.Object#wait()}.
+   * </p>
+   * <p>
+   * Use of this method requires virtual machine support
+   * for thread contention monitoring and for this support
+   * to be enabled.
+   * </p>
+   * 
+   * @return the accumulated time (in milliseconds) that this
+   *         thread has spent in the blocked state, since
+   *         thread contention monitoring was enabled, or -1
+   *         if thread contention monitoring is disabled.
+   * @throws UnsupportedOperationException if the virtual
+   *                                       machine does not
+   *                                       support contention
+   *                                       monitoring.
+   * @see ThreadMXBean#isThreadContentionMonitoringEnabled()
+   * @see ThreadMXBean#isThreadContentionMonitoringSupported()
+   */
+  public long getBlockedTime()
+  {
+    if (bean == null)
+      bean = ManagementFactory.getThreadMXBean();
+    // Will throw UnsupportedOperationException for us
+    if (bean.isThreadContentionMonitoringEnabled())
+      return VMThreadInfo.getBlockedTime(thread);
+    else
+      return -1;
+  }
+
+  /**
+   * <p>
+   * Returns a {@link java.lang.String} representation of
+   * the monitor lock on which this thread is blocked.  If
+   * the thread is not blocked, this method returns
+   * <code>null</code>.
+   * </p>
+   * <p>
+   * The returned {@link java.lang.String} is constructed
+   * using the class name and identity hashcode (usually
+   * the memory address of the object) of the lock.  The
+   * two are separated by the '@' character, and the identity
+   * hashcode is represented in hexadecimal.  Thus, for a
+   * lock, <code>l</code>, the returned value is
+   * the result of concatenating
+   * <code>l.getClass().getName()</code>, <code>"@"</code>
+   * and
+   * <code>Integer.toHexString(System.identityHashCode(l))</code>.
+   * The value is only unique to the extent that the identity
+   * hash code is also unique.
+   * </p>
+   *
+   * @return a string representing the lock on which this
+   *         thread is blocked, or <code>null</code> if
+   *         the thread is not blocked.
+   */
+  public String getLockName()
+  {
+    if (thread.getState().equals("BLOCKED"))
+      return null;
+    Object lock = VMThreadInfo.getLock(thread);
+    return lock.getClass().getName() + "@" +
+      Integer.toHexString(System.identityHashCode(lock));
+  }
+
+  /**
+   * Returns the identifier of the thread which owns the
+   * monitor lock this thread is waiting for.  -1 is returned
+   * if either this thread is not blocked, or the lock is
+   * not held by any other thread.
+   * 
+   * @return the thread identifier of thread holding the lock
+   *         this thread is waiting for, or -1 if the thread
+   *         is not blocked or the lock is not held by another
+   *         thread.
+   */
+  public long getLockOwnerId()
+  {
+    if (thread.getState().equals("BLOCKED"))
+      return -1;
+    Thread lockOwner = VMThreadInfo.getLockOwner(thread);
+    if (lockOwner == null)
+      return -1;
+    return lockOwner.getId();
+  }
+
+  /**
+   * Returns the name of the thread which owns the
+   * monitor lock this thread is waiting for.  <code>null</code>
+   * is returned if either this thread is not blocked,
+   * or the lock is not held by any other thread.
+   * 
+   * @return the thread identifier of thread holding the lock
+   *         this thread is waiting for, or <code>null</code>
+   *         if the thread is not blocked or the lock is not
+   *         held by another thread.
+   */
+  public String getLockOwnerName()
+  {
+    if (thread.getState().equals("BLOCKED"))
+      return null;
+    Thread lockOwner = VMThreadInfo.getLockOwner(thread);
+    if (lockOwner == null)
+      return null;
+    return lockOwner.getName();
+  }
+
+  /**
+   * <p>
+   * Returns the stack trace of this thread to the depth
+   * specified on creation of this {@link ThreadInfo}
+   * object.  If the depth is zero, an empty array will
+   * be returned.  For non-zero arrays, the elements
+   * start with the most recent trace at position zero.
+   * The bottom of the stack represents the oldest method
+   * invocation which meets the depth requirements.
+   * </p>
+   * <p>
+   * Some virtual machines may not be able to return
+   * stack trace information for a thread.  In these
+   * cases, an empty array will also be returned.
+   * </p>
+   * 
+   * @return an array of {@link java.lang.StackTraceElement}s
+   *         representing the trace of this thread.
+   */
+  public StackTraceElement[] getStackTrace()
+  {
+    if (maxDepth == 0)
+      return new StackTraceElement[0];
+    return VMThreadInfo.getStackTrace(thread, maxDepth);
+  }
+
+  /**
+   * Returns the identifier of the thread associated with
+   * this instance of {@link ThreadInfo}.
+   *
+   * @return the thread's identifier.
+   */
+  public long getThreadId()
+  {
+    return thread.getId();
+  }
+
+  /**
+   * Returns the name of the thread associated with
+   * this instance of {@link ThreadInfo}.
+   *
+   * @return the thread's name.
+   */
+  public String getThreadName()
+  {
+    return thread.getName();
+  }
+
+  /**
+   * Returns the state of the thread associated with
+   * this instance of {@link ThreadInfo}.
+   *
+   * @return the thread's state.
+   */
+  public String getThreadState()
+  {
+    return thread.getState();
+  }
+    
+  /**
+   * Returns the number of times this thread has been
+   * in the {@link java.lang.Thread.State#WAITING} 
+   * or {@link java.lang.Thread.State#TIMED_WAITING} state.
+   * A thread enters one of these states when it is waiting
+   * due to a call to {@link java.lang.Object.wait()},
+   * {@link java.lang.Object.join()} or
+   * {@link java.lang.concurrent.locks.LockSupport.park()},
+   * either with an infinite or timed delay, respectively. 
+   *
+   * @return the number of times this thread has been waiting.
+   */
+  public long getWaitedCount()
+  {
+    return VMThreadInfo.getWaitedCount(thread);
+  }
+
+  /**
+   * <p>
+   * Returns the accumulated number of milliseconds this
+   * thread has been in the
+   * {@link java.lang.Thread.State#WAITING} or
+   * {@link java.lang.Thread.State#TIMED_WAITING} state,
+   * since thread contention monitoring was last enabled.
+   * A thread enters one of these states when it is waiting
+   * due to a call to {@link java.lang.Object.wait()},
+   * {@link java.lang.Object.join()} or
+   * {@link java.lang.concurrent.locks.LockSupport.park()},
+   * either with an infinite or timed delay, respectively. 
+   * </p>
+   * <p>
+   * Use of this method requires virtual machine support
+   * for thread contention monitoring and for this support
+   * to be enabled.
+   * </p>
+   * 
+   * @return the accumulated time (in milliseconds) that this
+   *         thread has spent in one of the waiting states, since
+   *         thread contention monitoring was enabled, or -1
+   *         if thread contention monitoring is disabled.
+   * @throws UnsupportedOperationException if the virtual
+   *                                       machine does not
+   *                                       support contention
+   *                                       monitoring.
+   * @see ThreadMXBean#isThreadContentionMonitoringEnabled()
+   * @see ThreadMXBean#isThreadContentionMonitoringSupported()
+   */
+  public long getWaitedTime()
+  {
+    if (bean == null)
+      bean = ManagementFactory.getThreadMXBean();
+    // Will throw UnsupportedOperationException for us
+    if (bean.isThreadContentionMonitoringEnabled())
+      return VMThreadInfo.getWaitedTime(thread);
+    else
+      return -1;
+  }
+
+  /**
+   * Returns true if the thread is in a native method.  This
+   * excludes native code which forms part of the virtual
+   * machine itself, or which results from Just-In-Time
+   * compilation.
+   *
+   * @return true if the thread is in a native method, false
+   *         otherwise.
+   */
+  public boolean isInNative()
+  {
+    return VMThreadInfo.isInNative(thread);
+  }
+
+  /**
+   * Returns true if the thread has been suspended using
+   * {@link java.lang.Thread#suspend()}.
+   *
+   * @return true if the thread is suspended, false otherwise.
+   */
+  public boolean isSuspended()
+  {
+    return VMThreadInfo.isSuspended(thread);
+  }
+
+  /**
+   * Returns a {@link java.lang.String} representation of
+   * this {@link ThreadInfo} object.  This takes the form
+   * <code>java.lang.ThreadInfo[id=tid, maxDepth=md]</code>,
+   * where <code>tid</code> is the thread identifier
+   * and <code>md</code> is the maximum depth used by
+   * this {@link ThreadInfo}.
+   *
+   * @return the string specified above.
+   */
+  public String toString()
+  {
+    return getClass().getName() +
+      "[id=" + thread.getId() + ", maxDepth=" +
+      maxDepth + "]";
+  }
+
+}
diff --git a/java/lang/management/ThreadMXBean.java b/java/lang/management/ThreadMXBean.java
new file mode 100644
index 000000000..4e40e7fd3
--- /dev/null
+++ b/java/lang/management/ThreadMXBean.java
@@ -0,0 +1,497 @@
+/* ThreadMXBean.java - Interface for a thread bean
+   Copyright (C) 2006 Free Software Foundation
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath 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
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+package java.lang.management;
+
+/**
+ * <p>
+ * Provides access to information about the threads 
+ * of the virtual machine.  An instance of this bean is
+ * obtained by calling
+ * {@link ManagementFactory#getThreadMXBean()}.
+ * </p>
+ * <p>
+ * Each thread within the virtual machine is given an
+ * identifier, which is guaranteed to be unique to a
+ * particular thread over its lifetime (after which it
+ * may be reused). The identifier for a thread may be
+ * obtained by calling {@link java.lang.Thread#getId()}.
+ * This identifier is used within implementations of this
+ * interface to obtain information about a particular thread
+ * (or series of threads, in the case of an array of identifiers).
+ * </p>
+ * <p>
+ * This bean supports some optional behaviour, which all
+ * virtual machines may not choose to implement.  Specifically,
+ * this includes the monitoring of the CPU time used by a
+ * thread, and the monitoring of thread contention.  The former
+ * is further subdivided into the monitoring of either just
+ * the current thread or all threads.  The methods
+ * {@link #isThreadCpuTimeSupported()},
+ * {@link #isCurrentThreadCpuTimeSupported()} and
+ * {@link #isThreadContentionMonitoringSupported()} may be
+ * used to determine whether or not this functionality is
+ * supported.
+ * </p>
+ * <p>
+ * Furthermore, both these facilities may be disabled.
+ * In fact, thread contention monitoring is disabled by
+ * default, and must be explictly turned on by calling
+ * the {@link #setThreadContentionMonitoringEnabled(boolean)}
+ * method.
+ * </p>
+ *
+ * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
+ * @since 1.5
+ */
+public interface ThreadMXBean
+{
+
+  /**
+   * <p>
+   * This method obtains a list of threads which are deadlocked
+   * waiting to obtain monitor ownership.  On entering a synchronized
+   * method of an object, or re-entering it after returning from an
+   * {@link java.lang.Object#wait()} call, a thread obtains ownership
+   * of the object's monitor.  
+   * </p>
+   * <p>
+   * Deadlocks can occur in this situation if one or more threads end up
+   * waiting for a monitor, P, while also retaining ownership of a monitor,
+   * Q, required by the thread that currently owns P.  To give a simple
+   * example, imagine thread A calls a synchronized method, R, obtaining the
+   * monitor, P.  It then sleeps within that method, allowing thread B
+   * to run, but still retaining ownership of P.  B calls another
+   * synchronized method, S, which causes it to obtain the monitor, Q,
+   * of a different object.  While in that method, it then wants to
+   * call the original synchronized method, R,  called by A.  Doing so
+   * requires ownership of P, which is still held by A.  Hence, it
+   * becomes blocked.  
+   * </p>
+   * <p>
+   * A then finishes its sleep, becomes runnable, and is then allowed
+   * to run, being the only eligible thread in this scenario.  A tries
+   * to call the synchronized method, S.  It also gets blocked, because
+   * B still holds the monitor, Q.  Hence, the two threads, A and B,
+   * are deadlocked, as neither can give up its monitor without first
+   * obtaining the monitor held by the other thread.
+   * </p>
+   * <p>
+   * Calling this method in this scenario would return the thread IDs
+   * of A and B.  Note that this method is not designed for controlling
+   * synchronization, but for troubleshooting problems which cause such
+   * deadlocks; it may be prohibitively expensive to use in normal
+   * operation.
+   * </p>
+   * 
+   * @return an array of thread identifiers, corresponding to threads
+   *         which are currently in a deadlocked situation.
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("monitor").
+   */
+  long[] findMonitorDeadlockedThreads();
+
+  /**
+   * Returns all live thread identifiers at the time of initial
+   * execution.  Some thread identifiers in the returned array
+   * may refer to terminated threads, if this occurs during the
+   * lifetime of this method.
+   *
+   * @return an array of thread identifiers, corresponding to
+   *         current live threads.
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("monitor").
+   */
+  long[] getAllThreadIds();
+
+  /**
+   * <p>
+   * Returns the total number of nanoseconds of CPU time
+   * the current thread has used.  This is equivalent to calling
+   * <code>{@link #getThreadCpuTime()}(Thread.currentThread.getId())</code>.
+   * </p> 
+   * <p>
+   * Note that the value is only nanosecond-precise, and not accurate; there
+   * is no guarantee that the difference between two values is really a
+   * nanosecond.  Also, the value is prone to overflow if the offset
+   * exceeds 2^63.  The use of this method depends on virtual machine
+   * support for measurement of the CPU time of the current thread,
+   * and on this functionality being enabled.
+   * </p>
+   *
+   * @return the total number of nanoseconds of CPU time the current
+   *         thread has used, or -1 if CPU time monitoring is disabled.
+   * @throws UnsupportedOperationException if CPU time monitoring is not
+   *                                       supported.
+   * @see #getCurrentThreadUserTime()
+   * @see #isCurrentThreadCpuTimeSupported()
+   * @see #isThreadCpuTimeEnabled()
+   * @see #setThreadCpuTimeEnabled(boolean)
+   */
+  long getCurrentThreadCpuTime();
+
+  /**
+   * <p>
+   * Returns the total number of nanoseconds of CPU time
+   * the current thread has executed in user mode.  This is
+   * equivalent to calling
+   * <code>{@link #getThreadUserTime()}(Thread.currentThread.getId())</code>.
+   * </p> 
+   * <p>
+   * Note that the value is only nanosecond-precise, and not accurate; there
+   * is no guarantee that the difference between two values is really a
+   * nanosecond.  Also, the value is prone to overflow if the offset
+   * exceeds 2^63.  The use of this method depends on virtual machine
+   * support for measurement of the CPU time of the current thread,
+   * and on this functionality being enabled.
+   * </p>
+   *
+   * @return the total number of nanoseconds of CPU time the current
+   *         thread has executed in user mode, or -1 if CPU time
+   *         monitoring is disabled.
+   * @throws UnsupportedOperationException if CPU time monitoring is not
+   *                                       supported.
+   * @see #getCurrentThreadCpuTime()
+   * @see #isCurrentThreadCpuTimeSupported()
+   * @see #isThreadCpuTimeEnabled()
+   * @see #setThreadCpuTimeEnabled(boolean)
+   */
+  long getCurrentThreadUserTime();
+
+  /**
+   * Returns the number of live daemon threads.
+   *
+   * @return the number of live daemon threads.
+   */
+  int getDaemonThreadCount();
+
+  /**
+   * Returns the peak number of live threads since
+   * the virtual machine was started or the count
+   * reset using {@link #resetPeakThreadCount()}.
+   *
+   * @return the peak live thread count.
+   * @see #resetPeakThreadCount()
+   */
+  int getPeakThreadCount();
+
+  /**
+   * Returns the number of live threads, including
+   * both daemon threads and non-daemon threads.
+   *
+   * @return the current number of live threads.
+   */
+  int getThreadCount();
+
+  /**
+   * <p>
+   * Returns the total number of nanoseconds of CPU time
+   * the specified thread has used.  
+   * </p> 
+   * <p>
+   * Note that the value is only nanosecond-precise, and not accurate; there
+   * is no guarantee that the difference between two values is really a
+   * nanosecond.  Also, the value is prone to overflow if the offset
+   * exceeds 2^63.  The use of this method depends on virtual machine
+   * support for measurement of the CPU time of the current thread,
+   * and on this functionality being enabled.
+   * </p>
+   *
+   * @param id the thread identifier of the thread whose CPU time is being
+   *           monitored.
+   * @return the total number of nanoseconds of CPU time the specified
+   *         thread has used, or -1 if CPU time monitoring is disabled.
+   * @throws IllegalArgumentException if <code>id</code> <= 0.
+   * @throws UnsupportedOperationException if CPU time monitoring is not
+   *                                       supported.
+   * @see #getThreadUserTime(long)
+   * @see #isThreadCpuTimeSupported()
+   * @see #isThreadCpuTimeEnabled()
+   * @see #setThreadCpuTimeEnabled(boolean)
+   */
+  long getThreadCpuTime(long id);
+
+  /**
+   * Returns information on the specified thread without any
+   * stack trace information.  This is equivalent to
+   * <code>{@link #getThreadInfo}(id, 0)</code>.  If the
+   * identifier specifies a thread which is either non-existant
+   * or not alive, then the method returns <code>null</code>.
+   * 
+   * @param id the identifier of the thread to return information
+   *           on.
+   * @return a {@link ThreadInfo} object pertaining to the specified
+   *         thread, or <code>null</code> if the identifier specifies
+   *         a thread that doesn't exist or is not alive.
+   * @throws IllegalArgumentException if <code>id</code> <= 0.
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("monitor").
+   */
+  ThreadInfo getThreadInfo(long id);
+
+  /**
+   * Returns information on the specified threads without any
+   * stack trace information.  This is equivalent to
+   * <code>{@link #getThreadInfo}(ids, 0)</code>.  If an
+   * identifier specifies a thread which is either non-existant
+   * or not alive, then the corresponding element in the returned
+   * array is <code>null</code>.
+   * 
+   * @param ids an array of thread identifiers to return information
+   *           on.
+   * @return an array of {@link ThreadInfo} objects matching the
+   *         specified threads.  The corresponding element is 
+   *         <code>null</code> if the identifier specifies
+   *         a thread that doesn't exist or is not alive.
+   * @throws IllegalArgumentException if an identifier in the array is
+   *                                  <= 0.
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("monitor").
+   */
+  ThreadInfo getThreadInfo(long[] ids);
+
+  /**
+   * Returns information on the specified thread with
+   * stack trace information to the supplied depth.  If the
+   * identifier specifies a thread which is either non-existant
+   * or not alive, then the method returns <code>null</code>.
+   * A maximum depth of 0 corresponds to an empty stack trace
+   * (an empty array is returned by the appropriate
+   * {@link ThreadInfo} method).  A maximum depth of
+   * <code>Integer.MAX_VALUE</code> returns the full stack trace.
+   *
+   * @param id the identifier of the thread to return information
+   *           on.
+   * @param maxDepth the maximum depth of the stack trace.
+   *                 Values of 0 or <code>Integer.MAX_VALUE</code>
+   *                 correspond to an empty and full stack trace
+   *                 respectively.
+   * @return a {@link ThreadInfo} object pertaining to the specified
+   *         thread, or <code>null</code> if the identifier specifies
+   *         a thread that doesn't exist or is not alive.
+   * @throws IllegalArgumentException if <code>id</code> <= 0.
+   * @throws IllegalArgumentException if <code>maxDepth</code> <= 0.
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("monitor").
+   */
+  ThreadInfo getThreadInfo(long id, int maxDepth);
+
+  /**
+   * Returns information on the specified threads with
+   * stack trace information to the supplied depth.  If an
+   * identifier specifies a thread which is either non-existant
+   * or not alive, then the corresponding element in the returned
+   * array is <code>null</code>.  A maximum depth of 0 corresponds
+   * to an empty stack trace (an empty array is returned by the
+   * appropriate {@link ThreadInfo} method).  A maximum depth of
+   * <code>Integer.MAX_VALUE</code> returns the full stack trace.
+   * 
+   * @param ids an array of thread identifiers to return information
+   *           on.
+   * @param maxDepth the maximum depth of the stack trace.
+   *                 Values of 0 or <code>Integer.MAX_VALUE</code>
+   *                 correspond to an empty and full stack trace
+   *                 respectively.
+   * @return an array of {@link ThreadInfo} objects matching the
+   *         specified threads.  The corresponding element is 
+   *         <code>null</code> if the identifier specifies
+   *         a thread that doesn't exist or is not alive.
+   * @throws IllegalArgumentException if an identifier in the array is
+   *                                  <= 0.
+   * @throws IllegalArgumentException if <code>maxDepth</code> <= 0.
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("monitor").
+   */
+  ThreadInfo getThreadInfo(long[] ids, int maxDepth);
+
+  /**
+   * <p>
+   * Returns the total number of nanoseconds of CPU time
+   * the specified thread has executed in user mode.  
+   * </p> 
+   * <p>
+   * Note that the value is only nanosecond-precise, and not accurate; there
+   * is no guarantee that the difference between two values is really a
+   * nanosecond.  Also, the value is prone to overflow if the offset
+   * exceeds 2^63.  The use of this method depends on virtual machine
+   * support for measurement of the CPU time of the current thread,
+   * and on this functionality being enabled.
+   * </p>
+   *
+   * @param id the thread identifier of the thread whose CPU time is being
+   *           monitored.
+   * @return the total number of nanoseconds of CPU time the specified
+   *         thread has executed in user mode, or -1 if CPU time monitoring
+   *         is disabled.
+   * @throws IllegalArgumentException if <code>id</code> <= 0.
+   * @throws UnsupportedOperationException if CPU time monitoring is not
+   *                                       supported.
+   * @see #getThreadCpuTime(long)
+   * @see #isThreadCpuTimeSupported()
+   * @see #isThreadCpuTimeEnabled()
+   * @see #setThreadCpuTimeEnabled(boolean)
+   */
+  long getThreadUserTime(long id);
+
+  /**
+   * Returns the total number of threads that have been
+   * created and started during the lifetime of the virtual
+   * machine.
+   *
+   * @return the total number of started threads.
+   */
+  long getTotalStartedThreadCount();
+
+  /**
+   * Returns true if the virtual machine supports the monitoring
+   * of the CPU time used by the current thread.  This is implied
+   * by {@link isThreadCpuTimeSupported()} returning true.
+   *
+   * @return true if monitoring of the CPU time used by the current
+   *         thread is supported by the virtual machine.
+   * @see #isThreadCpuTimeEnabled()
+   * @see #isThreadCpuTimeSupported()
+   * @see #setThreadCpuTimeEnabled(boolean)
+   */
+  boolean isCurrentThreadCpuTimeSupported();
+
+  /**
+   * Returns true if thread contention monitoring is currently
+   * enabled.
+   *
+   * @return true if thread contention monitoring is enabled.
+   * @throws UnsupportedOperationException if the virtual
+   *                                       machine does not
+   *                                       support contention
+   *                                       monitoring.
+   * @see #isThreadContentionMonitoringSupported()
+   * @see #setThreadContentionMonitoringEnabled(boolean)
+   */
+  boolean isThreadContentionMonitoringEnabled();
+
+  /**
+   * Returns true if thread contention monitoring is supported
+   * by the virtual machine.
+   *
+   * @return true if thread contention monitoring is supported
+   *         by the virtual machine.
+   * @see #isThreadContentionMonitoringEnabled()
+   * @see #setThreadContentionMonitoringEnabled(boolean)
+   */
+  boolean isThreadContentionMonitoringSupported();
+
+  /**
+   * Returns true if monitoring of the CPU time used by a thread
+   * is currently enabled.
+   *
+   * @return true if thread CPU time monitoring is enabled.
+   * @throws UnsupportedOperationException if the virtual
+   *                                       machine does not
+   *                                       support CPU time
+   *                                       monitoring.
+   * @see #isCurrentThreadCpuTimeSupported()
+   * @see #isThreadCpuTimeSupported()
+   * @see #setThreadCpuTimeEnabled(boolean)
+   */
+  boolean isThreadCpuTimeEnabled();
+
+  /**
+   * Returns true if the virtual machine supports the monitoring
+   * of the CPU time used by all threads.  This implies
+   * that {@link isCurrentThreadCpuTimeSupported()} returns true.
+   *
+   * @return true if monitoring of the CPU time used by the current
+   *         thread is supported by the virtual machine.
+   * @see #isCurrentThreadCpuTimeSupported()
+   * @see #isThreadCpuTimeEnabled()
+   * @see #setThreadCpuTimeEnabled(boolean)
+   */
+  boolean isThreadCpuTimeSupported();
+
+  /**
+   * Resets the peak live thread count to the
+   * current number of live threads, as returned
+   * by {@link #getThreadCount()}.
+   *
+   * @see #getPeakThreadCount()
+   * @see #getThreadCount()
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("control").
+   */
+  void resetPeakThreadCount();
+
+  /**
+   * Toggles the monitoring of thread contention.  Thread
+   * contention monitoring is disabled by default.  Each
+   * time contention monitoring is re-enabled, the times
+   * it maintains are reset.
+   *
+   * @param enable true if monitoring should be enabled,
+   *               false if it should be disabled.
+   * @throws UnsupportedOperationException if the virtual
+   *                                       machine does not
+   *                                       support contention
+   *                                       monitoring.
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("control").
+   * @see #isThreadContentionMonitoringEnabled()
+   * @see #isThreadContentionMonitoringSupported()
+   */
+  void setThreadContentionMonitoringEnabled(boolean enable);
+
+  /**
+   * Toggles the monitoring of CPU time used by threads. The
+   * initial setting is dependent on the underlying virtual
+   * machine.  On enabling CPU time monitoring, the virtual
+   * machine may take any value up to and including the current
+   * time as the start time for monitoring.
+   *
+   * @param enable true if monitoring should be enabled,
+   *               false if it should be disabled.
+   * @throws UnsupportedOperationException if the virtual
+   *                                       machine does not
+   *                                       support CPU time
+   *                                       monitoring.
+   * @throws SecurityException if a security manager exists and
+   *                           denies ManagementPermission("control").
+   * @see #isCurrentThreadCpuTimeSupported()
+   * @see #isThreadCpuTimeEnabled()
+   * @see #isThreadCpuTimeSupported()
+   */
+  void setThreadCpuTimeEnabled(boolean enable);
+
+}