View Javadoc
1   /*
2    * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package java.lang.management;
27  
28  import java.util.Map;
29  
30  /**
31   * The management interface for the thread system of
32   * the Java virtual machine.
33   *
34   * <p> A Java virtual machine has a single instance of the implementation
35   * class of this interface.  This instance implementing this interface is
36   * an <a href="ManagementFactory.html#MXBean">MXBean</a>
37   * that can be obtained by calling
38   * the {@link ManagementFactory#getThreadMXBean} method or
39   * from the {@link ManagementFactory#getPlatformMBeanServer
40   * platform <tt>MBeanServer</tt>} method.
41   *
42   * <p>The <tt>ObjectName</tt> for uniquely identifying the MXBean for
43   * the thread system within an MBeanServer is:
44   * <blockquote>
45   *    {@link ManagementFactory#THREAD_MXBEAN_NAME
46   *           <tt>java.lang:type=Threading</tt>}
47   * </blockquote>
48   *
49   * It can be obtained by calling the
50   * {@link PlatformManagedObject#getObjectName} method.
51   *
52   * <h3>Thread ID</h3>
53   * Thread ID is a positive long value returned by calling the
54   * {@link java.lang.Thread#getId} method for a thread.
55   * The thread ID is unique during its lifetime.  When a thread
56   * is terminated, this thread ID may be reused.
57   *
58   * <p> Some methods in this interface take a thread ID or an array
59   * of thread IDs as the input parameter and return per-thread information.
60   *
61   * <h3>Thread CPU time</h3>
62   * A Java virtual machine implementation may support measuring
63   * the CPU time for the current thread, for any thread, or for no threads.
64   *
65   * <p>
66   * The {@link #isThreadCpuTimeSupported} method can be used to determine
67   * if a Java virtual machine supports measuring of the CPU time for any
68   * thread.  The {@link #isCurrentThreadCpuTimeSupported} method can
69   * be used to determine if a Java virtual machine supports measuring of
70   * the CPU time for the current  thread.
71   * A Java virtual machine implementation that supports CPU time measurement
72   * for any thread will also support that for the current thread.
73   *
74   * <p> The CPU time provided by this interface has nanosecond precision
75   * but not necessarily nanosecond accuracy.
76   *
77   * <p>
78   * A Java virtual machine may disable CPU time measurement
79   * by default.
80   * The {@link #isThreadCpuTimeEnabled} and {@link #setThreadCpuTimeEnabled}
81   * methods can be used to test if CPU time measurement is enabled
82   * and to enable/disable this support respectively.
83   * Enabling thread CPU measurement could be expensive in some
84   * Java virtual machine implementations.
85   *
86   * <h3>Thread Contention Monitoring</h3>
87   * Some Java virtual machines may support thread contention monitoring.
88   * When thread contention monitoring is enabled, the accumulated elapsed
89   * time that the thread has blocked for synchronization or waited for
90   * notification will be collected and returned in the
91   * <a href="ThreadInfo.html#SyncStats"><tt>ThreadInfo</tt></a> object.
92   * <p>
93   * The {@link #isThreadContentionMonitoringSupported} method can be used to
94   * determine if a Java virtual machine supports thread contention monitoring.
95   * The thread contention monitoring is disabled by default.  The
96   * {@link #setThreadContentionMonitoringEnabled} method can be used to enable
97   * thread contention monitoring.
98   *
99   * <h3>Synchronization Information and Deadlock Detection</h3>
100  * Some Java virtual machines may support monitoring of
101  * {@linkplain #isObjectMonitorUsageSupported object monitor usage} and
102  * {@linkplain #isSynchronizerUsageSupported ownable synchronizer usage}.
103  * The {@link #getThreadInfo(long[], boolean, boolean)} and
104  * {@link #dumpAllThreads} methods can be used to obtain the thread stack trace
105  * and synchronization information including which
106  * {@linkplain LockInfo <i>lock</i>} a thread is blocked to
107  * acquire or waiting on and which locks the thread currently owns.
108  * <p>
109  * The <tt>ThreadMXBean</tt> interface provides the
110  * {@link #findMonitorDeadlockedThreads} and
111  * {@link #findDeadlockedThreads} methods to find deadlocks in
112  * the running application.
113  *
114  * @see ManagementFactory#getPlatformMXBeans(Class)
115  * @see <a href="../../../javax/management/package-summary.html">
116  *      JMX Specification.</a>
117  * @see <a href="package-summary.html#examples">
118  *      Ways to Access MXBeans</a>
119  *
120  * @author  Mandy Chung
121  * @since   1.5
122  */
123 
124 public interface ThreadMXBean extends PlatformManagedObject {
125     /**
126      * Returns the current number of live threads including both
127      * daemon and non-daemon threads.
128      *
129      * @return the current number of live threads.
130      */
131     public int getThreadCount();
132 
133     /**
134      * Returns the peak live thread count since the Java virtual machine
135      * started or peak was reset.
136      *
137      * @return the peak live thread count.
138      */
139     public int getPeakThreadCount();
140 
141     /**
142      * Returns the total number of threads created and also started
143      * since the Java virtual machine started.
144      *
145      * @return the total number of threads started.
146      */
147     public long getTotalStartedThreadCount();
148 
149     /**
150      * Returns the current number of live daemon threads.
151      *
152      * @return the current number of live daemon threads.
153      */
154     public int getDaemonThreadCount();
155 
156     /**
157      * Returns all live thread IDs.
158      * Some threads included in the returned array
159      * may have been terminated when this method returns.
160      *
161      * @return an array of <tt>long</tt>, each is a thread ID.
162      *
163      * @throws java.lang.SecurityException if a security manager
164      *         exists and the caller does not have
165      *         ManagementPermission("monitor").
166      */
167     public long[] getAllThreadIds();
168 
169     /**
170      * Returns the thread info for a thread of the specified
171      * <tt>id</tt> with no stack trace.
172      * This method is equivalent to calling:
173      * <blockquote>
174      *   {@link #getThreadInfo(long, int) getThreadInfo(id, 0);}
175      * </blockquote>
176      *
177      * <p>
178      * This method returns a <tt>ThreadInfo</tt> object representing
179      * the thread information for the thread of the specified ID.
180      * The stack trace, locked monitors, and locked synchronizers
181      * in the returned <tt>ThreadInfo</tt> object will
182      * be empty.
183      *
184      * If a thread of the given ID is not alive or does not exist,
185      * this method will return <tt>null</tt>.  A thread is alive if
186      * it has been started and has not yet died.
187      *
188      * <p>
189      * <b>MBeanServer access</b>:<br>
190      * The mapped type of <tt>ThreadInfo</tt> is
191      * <tt>CompositeData</tt> with attributes as specified in the
192      * {@link ThreadInfo#from ThreadInfo.from} method.
193      *
194      * @param id the thread ID of the thread. Must be positive.
195      *
196      * @return a {@link ThreadInfo} object for the thread of the given ID
197      * with no stack trace, no locked monitor and no synchronizer info;
198      * <tt>null</tt> if the thread of the given ID is not alive or
199      * it does not exist.
200      *
201      * @throws IllegalArgumentException if {@code id <= 0}.
202      * @throws java.lang.SecurityException if a security manager
203      *         exists and the caller does not have
204      *         ManagementPermission("monitor").
205      */
206     public ThreadInfo getThreadInfo(long id);
207 
208     /**
209      * Returns the thread info for each thread
210      * whose ID is in the input array <tt>ids</tt> with no stack trace.
211      * This method is equivalent to calling:
212      * <blockquote><pre>
213      *   {@link #getThreadInfo(long[], int) getThreadInfo}(ids, 0);
214      * </pre></blockquote>
215      *
216      * <p>
217      * This method returns an array of the <tt>ThreadInfo</tt> objects.
218      * The stack trace, locked monitors, and locked synchronizers
219      * in each <tt>ThreadInfo</tt> object will be empty.
220      *
221      * If a thread of a given ID is not alive or does not exist,
222      * the corresponding element in the returned array will
223      * contain <tt>null</tt>.  A thread is alive if
224      * it has been started and has not yet died.
225      *
226      * <p>
227      * <b>MBeanServer access</b>:<br>
228      * The mapped type of <tt>ThreadInfo</tt> is
229      * <tt>CompositeData</tt> with attributes as specified in the
230      * {@link ThreadInfo#from ThreadInfo.from} method.
231      *
232      * @param ids an array of thread IDs.
233      * @return an array of the {@link ThreadInfo} objects, each containing
234      * information about a thread whose ID is in the corresponding
235      * element of the input array of IDs
236      * with no stack trace, no locked monitor and no synchronizer info.
237      *
238      * @throws IllegalArgumentException if any element in the input array
239      *         <tt>ids</tt> is {@code <= 0}.
240      * @throws java.lang.SecurityException if a security manager
241      *         exists and the caller does not have
242      *         ManagementPermission("monitor").
243      */
244     public ThreadInfo[] getThreadInfo(long[] ids);
245 
246     /**
247      * Returns a thread info for a thread of the specified <tt>id</tt>,
248      * with stack trace of a specified number of stack trace elements.
249      * The <tt>maxDepth</tt> parameter indicates the maximum number of
250      * {@link StackTraceElement} to be retrieved from the stack trace.
251      * If <tt>maxDepth == Integer.MAX_VALUE</tt>, the entire stack trace of
252      * the thread will be dumped.
253      * If <tt>maxDepth == 0</tt>, no stack trace of the thread
254      * will be dumped.
255      * This method does not obtain the locked monitors and locked
256      * synchronizers of the thread.
257      * <p>
258      * When the Java virtual machine has no stack trace information
259      * about a thread or <tt>maxDepth == 0</tt>,
260      * the stack trace in the
261      * <tt>ThreadInfo</tt> object will be an empty array of
262      * <tt>StackTraceElement</tt>.
263      *
264      * <p>
265      * If a thread of the given ID is not alive or does not exist,
266      * this method will return <tt>null</tt>.  A thread is alive if
267      * it has been started and has not yet died.
268      *
269      * <p>
270      * <b>MBeanServer access</b>:<br>
271      * The mapped type of <tt>ThreadInfo</tt> is
272      * <tt>CompositeData</tt> with attributes as specified in the
273      * {@link ThreadInfo#from ThreadInfo.from} method.
274      *
275      * @param id the thread ID of the thread. Must be positive.
276      * @param maxDepth the maximum number of entries in the stack trace
277      * to be dumped. <tt>Integer.MAX_VALUE</tt> could be used to request
278      * the entire stack to be dumped.
279      *
280      * @return a {@link ThreadInfo} of the thread of the given ID
281      * with no locked monitor and synchronizer info.
282      * <tt>null</tt> if the thread of the given ID is not alive or
283      * it does not exist.
284      *
285      * @throws IllegalArgumentException if {@code id <= 0}.
286      * @throws IllegalArgumentException if <tt>maxDepth is negative</tt>.
287      * @throws java.lang.SecurityException if a security manager
288      *         exists and the caller does not have
289      *         ManagementPermission("monitor").
290      *
291      */
292     public ThreadInfo getThreadInfo(long id, int maxDepth);
293 
294     /**
295      * Returns the thread info for each thread
296      * whose ID is in the input array <tt>ids</tt>,
297      * with stack trace of a specified number of stack trace elements.
298      * The <tt>maxDepth</tt> parameter indicates the maximum number of
299      * {@link StackTraceElement} to be retrieved from the stack trace.
300      * If <tt>maxDepth == Integer.MAX_VALUE</tt>, the entire stack trace of
301      * the thread will be dumped.
302      * If <tt>maxDepth == 0</tt>, no stack trace of the thread
303      * will be dumped.
304      * This method does not obtain the locked monitors and locked
305      * synchronizers of the threads.
306      * <p>
307      * When the Java virtual machine has no stack trace information
308      * about a thread or <tt>maxDepth == 0</tt>,
309      * the stack trace in the
310      * <tt>ThreadInfo</tt> object will be an empty array of
311      * <tt>StackTraceElement</tt>.
312      * <p>
313      * This method returns an array of the <tt>ThreadInfo</tt> objects,
314      * each is the thread information about the thread with the same index
315      * as in the <tt>ids</tt> array.
316      * If a thread of the given ID is not alive or does not exist,
317      * <tt>null</tt> will be set in the corresponding element
318      * in the returned array.  A thread is alive if
319      * it has been started and has not yet died.
320      *
321      * <p>
322      * <b>MBeanServer access</b>:<br>
323      * The mapped type of <tt>ThreadInfo</tt> is
324      * <tt>CompositeData</tt> with attributes as specified in the
325      * {@link ThreadInfo#from ThreadInfo.from} method.
326      *
327      * @param ids an array of thread IDs
328      * @param maxDepth the maximum number of entries in the stack trace
329      * to be dumped. <tt>Integer.MAX_VALUE</tt> could be used to request
330      * the entire stack to be dumped.
331      *
332      * @return an array of the {@link ThreadInfo} objects, each containing
333      * information about a thread whose ID is in the corresponding
334      * element of the input array of IDs with no locked monitor and
335      * synchronizer info.
336      *
337      * @throws IllegalArgumentException if <tt>maxDepth is negative</tt>.
338      * @throws IllegalArgumentException if any element in the input array
339      *      <tt>ids</tt> is {@code <= 0}.
340      * @throws java.lang.SecurityException if a security manager
341      *         exists and the caller does not have
342      *         ManagementPermission("monitor").
343      *
344      */
345     public ThreadInfo[] getThreadInfo(long[] ids, int maxDepth);
346 
347     /**
348      * Tests if the Java virtual machine supports thread contention monitoring.
349      *
350      * @return
351      *   <tt>true</tt>
352      *     if the Java virtual machine supports thread contention monitoring;
353      *   <tt>false</tt> otherwise.
354      */
355     public boolean isThreadContentionMonitoringSupported();
356 
357     /**
358      * Tests if thread contention monitoring is enabled.
359      *
360      * @return <tt>true</tt> if thread contention monitoring is enabled;
361      *         <tt>false</tt> otherwise.
362      *
363      * @throws java.lang.UnsupportedOperationException if the Java virtual
364      * machine does not support thread contention monitoring.
365      *
366      * @see #isThreadContentionMonitoringSupported
367      */
368     public boolean isThreadContentionMonitoringEnabled();
369 
370     /**
371      * Enables or disables thread contention monitoring.
372      * Thread contention monitoring is disabled by default.
373      *
374      * @param enable <tt>true</tt> to enable;
375      *               <tt>false</tt> to disable.
376      *
377      * @throws java.lang.UnsupportedOperationException if the Java
378      * virtual machine does not support thread contention monitoring.
379      *
380      * @throws java.lang.SecurityException if a security manager
381      *         exists and the caller does not have
382      *         ManagementPermission("control").
383      *
384      * @see #isThreadContentionMonitoringSupported
385      */
386     public void setThreadContentionMonitoringEnabled(boolean enable);
387 
388     /**
389      * Returns the total CPU time for the current thread in nanoseconds.
390      * The returned value is of nanoseconds precision but
391      * not necessarily nanoseconds accuracy.
392      * If the implementation distinguishes between user mode time and system
393      * mode time, the returned CPU time is the amount of time that
394      * the current thread has executed in user mode or system mode.
395      *
396      * <p>
397      * This is a convenient method for local management use and is
398      * equivalent to calling:
399      * <blockquote><pre>
400      *   {@link #getThreadCpuTime getThreadCpuTime}(Thread.currentThread().getId());
401      * </pre></blockquote>
402      *
403      * @return the total CPU time for the current thread if CPU time
404      * measurement is enabled; <tt>-1</tt> otherwise.
405      *
406      * @throws java.lang.UnsupportedOperationException if the Java
407      * virtual machine does not support CPU time measurement for
408      * the current thread.
409      *
410      * @see #getCurrentThreadUserTime
411      * @see #isCurrentThreadCpuTimeSupported
412      * @see #isThreadCpuTimeEnabled
413      * @see #setThreadCpuTimeEnabled
414      */
415     public long getCurrentThreadCpuTime();
416 
417     /**
418      * Returns the CPU time that the current thread has executed
419      * in user mode in nanoseconds.
420      * The returned value is of nanoseconds precision but
421      * not necessarily nanoseconds accuracy.
422      *
423      * <p>
424      * This is a convenient method for local management use and is
425      * equivalent to calling:
426      * <blockquote><pre>
427      *   {@link #getThreadUserTime getThreadUserTime}(Thread.currentThread().getId());
428      * </pre></blockquote>
429      *
430      * @return the user-level CPU time for the current thread if CPU time
431      * measurement is enabled; <tt>-1</tt> otherwise.
432      *
433      * @throws java.lang.UnsupportedOperationException if the Java
434      * virtual machine does not support CPU time measurement for
435      * the current thread.
436      *
437      * @see #getCurrentThreadCpuTime
438      * @see #isCurrentThreadCpuTimeSupported
439      * @see #isThreadCpuTimeEnabled
440      * @see #setThreadCpuTimeEnabled
441      */
442     public long getCurrentThreadUserTime();
443 
444     /**
445      * Returns the total CPU time for a thread of the specified ID in nanoseconds.
446      * The returned value is of nanoseconds precision but
447      * not necessarily nanoseconds accuracy.
448      * If the implementation distinguishes between user mode time and system
449      * mode time, the returned CPU time is the amount of time that
450      * the thread has executed in user mode or system mode.
451      *
452      * <p>
453      * If the thread of the specified ID is not alive or does not exist,
454      * this method returns <tt>-1</tt>. If CPU time measurement
455      * is disabled, this method returns <tt>-1</tt>.
456      * A thread is alive if it has been started and has not yet died.
457      * <p>
458      * If CPU time measurement is enabled after the thread has started,
459      * the Java virtual machine implementation may choose any time up to
460      * and including the time that the capability is enabled as the point
461      * where CPU time measurement starts.
462      *
463      * @param id the thread ID of a thread
464      * @return the total CPU time for a thread of the specified ID
465      * if the thread of the specified ID exists, the thread is alive,
466      * and CPU time measurement is enabled;
467      * <tt>-1</tt> otherwise.
468      *
469      * @throws IllegalArgumentException if {@code id <= 0}.
470      * @throws java.lang.UnsupportedOperationException if the Java
471      * virtual machine does not support CPU time measurement for
472      * other threads.
473      *
474      * @see #getThreadUserTime
475      * @see #isThreadCpuTimeSupported
476      * @see #isThreadCpuTimeEnabled
477      * @see #setThreadCpuTimeEnabled
478      */
479     public long getThreadCpuTime(long id);
480 
481     /**
482      * Returns the CPU time that a thread of the specified ID
483      * has executed in user mode in nanoseconds.
484      * The returned value is of nanoseconds precision but
485      * not necessarily nanoseconds accuracy.
486      *
487      * <p>
488      * If the thread of the specified ID is not alive or does not exist,
489      * this method returns <tt>-1</tt>. If CPU time measurement
490      * is disabled, this method returns <tt>-1</tt>.
491      * A thread is alive if it has been started and has not yet died.
492      * <p>
493      * If CPU time measurement is enabled after the thread has started,
494      * the Java virtual machine implementation may choose any time up to
495      * and including the time that the capability is enabled as the point
496      * where CPU time measurement starts.
497      *
498      * @param id the thread ID of a thread
499      * @return the user-level CPU time for a thread of the specified ID
500      * if the thread of the specified ID exists, the thread is alive,
501      * and CPU time measurement is enabled;
502      * <tt>-1</tt> otherwise.
503      *
504      * @throws IllegalArgumentException if {@code id <= 0}.
505      * @throws java.lang.UnsupportedOperationException if the Java
506      * virtual machine does not support CPU time measurement for
507      * other threads.
508      *
509      * @see #getThreadCpuTime
510      * @see #isThreadCpuTimeSupported
511      * @see #isThreadCpuTimeEnabled
512      * @see #setThreadCpuTimeEnabled
513      */
514     public long getThreadUserTime(long id);
515 
516     /**
517      * Tests if the Java virtual machine implementation supports CPU time
518      * measurement for any thread.
519      * A Java virtual machine implementation that supports CPU time
520      * measurement for any thread will also support CPU time
521      * measurement for the current thread.
522      *
523      * @return
524      *   <tt>true</tt>
525      *     if the Java virtual machine supports CPU time
526      *     measurement for any thread;
527      *   <tt>false</tt> otherwise.
528      */
529     public boolean isThreadCpuTimeSupported();
530 
531     /**
532      * Tests if the Java virtual machine supports CPU time
533      * measurement for the current thread.
534      * This method returns <tt>true</tt> if {@link #isThreadCpuTimeSupported}
535      * returns <tt>true</tt>.
536      *
537      * @return
538      *   <tt>true</tt>
539      *     if the Java virtual machine supports CPU time
540      *     measurement for current thread;
541      *   <tt>false</tt> otherwise.
542      */
543     public boolean isCurrentThreadCpuTimeSupported();
544 
545     /**
546      * Tests if thread CPU time measurement is enabled.
547      *
548      * @return <tt>true</tt> if thread CPU time measurement is enabled;
549      *         <tt>false</tt> otherwise.
550      *
551      * @throws java.lang.UnsupportedOperationException if the Java virtual
552      * machine does not support CPU time measurement for other threads
553      * nor for the current thread.
554      *
555      * @see #isThreadCpuTimeSupported
556      * @see #isCurrentThreadCpuTimeSupported
557      */
558     public boolean isThreadCpuTimeEnabled();
559 
560     /**
561      * Enables or disables thread CPU time measurement.  The default
562      * is platform dependent.
563      *
564      * @param enable <tt>true</tt> to enable;
565      *               <tt>false</tt> to disable.
566      *
567      * @throws java.lang.UnsupportedOperationException if the Java
568      * virtual machine does not support CPU time measurement for
569      * any threads nor for the current thread.
570      *
571      * @throws java.lang.SecurityException if a security manager
572      *         exists and the caller does not have
573      *         ManagementPermission("control").
574      *
575      * @see #isThreadCpuTimeSupported
576      * @see #isCurrentThreadCpuTimeSupported
577      */
578     public void setThreadCpuTimeEnabled(boolean enable);
579 
580     /**
581      * Finds cycles of threads that are in deadlock waiting to acquire
582      * object monitors. That is, threads that are blocked waiting to enter a
583      * synchronization block or waiting to reenter a synchronization block
584      * after an {@link Object#wait Object.wait} call,
585      * where each thread owns one monitor while
586      * trying to obtain another monitor already held by another thread
587      * in a cycle.
588      * <p>
589      * More formally, a thread is <em>monitor deadlocked</em> if it is
590      * part of a cycle in the relation "is waiting for an object monitor
591      * owned by".  In the simplest case, thread A is blocked waiting
592      * for a monitor owned by thread B, and thread B is blocked waiting
593      * for a monitor owned by thread A.
594      * <p>
595      * This method is designed for troubleshooting use, but not for
596      * synchronization control.  It might be an expensive operation.
597      * <p>
598      * This method finds deadlocks involving only object monitors.
599      * To find deadlocks involving both object monitors and
600      * <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>,
601      * the {@link #findDeadlockedThreads findDeadlockedThreads} method
602      * should be used.
603      *
604      * @return an array of IDs of the threads that are monitor
605      * deadlocked, if any; <tt>null</tt> otherwise.
606      *
607      * @throws java.lang.SecurityException if a security manager
608      *         exists and the caller does not have
609      *         ManagementPermission("monitor").
610      *
611      * @see #findDeadlockedThreads
612      */
613     public long[] findMonitorDeadlockedThreads();
614 
615     /**
616      * Resets the peak thread count to the current number of
617      * live threads.
618      *
619      * @throws java.lang.SecurityException if a security manager
620      *         exists and the caller does not have
621      *         ManagementPermission("control").
622      *
623      * @see #getPeakThreadCount
624      * @see #getThreadCount
625      */
626     public void resetPeakThreadCount();
627 
628     /**
629      * Finds cycles of threads that are in deadlock waiting to acquire
630      * object monitors or
631      * <a href="LockInfo.html#OwnableSynchronizer">ownable synchronizers</a>.
632      *
633      * Threads are <em>deadlocked</em> in a cycle waiting for a lock of
634      * these two types if each thread owns one lock while
635      * trying to acquire another lock already held
636      * by another thread in the cycle.
637      * <p>
638      * This method is designed for troubleshooting use, but not for
639      * synchronization control.  It might be an expensive operation.
640      *
641      * @return an array of IDs of the threads that are
642      * deadlocked waiting for object monitors or ownable synchronizers, if any;
643      * <tt>null</tt> otherwise.
644      *
645      * @throws java.lang.SecurityException if a security manager
646      *         exists and the caller does not have
647      *         ManagementPermission("monitor").
648      * @throws java.lang.UnsupportedOperationException if the Java virtual
649      * machine does not support monitoring of ownable synchronizer usage.
650      *
651      * @see #isSynchronizerUsageSupported
652      * @see #findMonitorDeadlockedThreads
653      * @since 1.6
654      */
655     public long[] findDeadlockedThreads();
656 
657     /**
658      * Tests if the Java virtual machine supports monitoring of
659      * object monitor usage.
660      *
661      * @return
662      *   <tt>true</tt>
663      *     if the Java virtual machine supports monitoring of
664      *     object monitor usage;
665      *   <tt>false</tt> otherwise.
666      *
667      * @see #dumpAllThreads
668      * @since 1.6
669      */
670     public boolean isObjectMonitorUsageSupported();
671 
672     /**
673      * Tests if the Java virtual machine supports monitoring of
674      * <a href="LockInfo.html#OwnableSynchronizer">
675      * ownable synchronizer</a> usage.
676      *
677      * @return
678      *   <tt>true</tt>
679      *     if the Java virtual machine supports monitoring of ownable
680      *     synchronizer usage;
681      *   <tt>false</tt> otherwise.
682      *
683      * @see #dumpAllThreads
684      * @since 1.6
685      */
686     public boolean isSynchronizerUsageSupported();
687 
688     /**
689      * Returns the thread info for each thread
690      * whose ID is in the input array <tt>ids</tt>, with stack trace
691      * and synchronization information.
692      *
693      * <p>
694      * This method obtains a snapshot of the thread information
695      * for each thread including:
696      * <ul>
697      *    <li>the entire stack trace,</li>
698      *    <li>the object monitors currently locked by the thread
699      *        if <tt>lockedMonitors</tt> is <tt>true</tt>, and</li>
700      *    <li>the <a href="LockInfo.html#OwnableSynchronizer">
701      *        ownable synchronizers</a> currently locked by the thread
702      *        if <tt>lockedSynchronizers</tt> is <tt>true</tt>.</li>
703      * </ul>
704      * <p>
705      * This method returns an array of the <tt>ThreadInfo</tt> objects,
706      * each is the thread information about the thread with the same index
707      * as in the <tt>ids</tt> array.
708      * If a thread of the given ID is not alive or does not exist,
709      * <tt>null</tt> will be set in the corresponding element
710      * in the returned array.  A thread is alive if
711      * it has been started and has not yet died.
712      * <p>
713      * If a thread does not lock any object monitor or <tt>lockedMonitors</tt>
714      * is <tt>false</tt>, the returned <tt>ThreadInfo</tt> object will have an
715      * empty <tt>MonitorInfo</tt> array.  Similarly, if a thread does not
716      * lock any synchronizer or <tt>lockedSynchronizers</tt> is <tt>false</tt>,
717      * the returned <tt>ThreadInfo</tt> object
718      * will have an empty <tt>LockInfo</tt> array.
719      *
720      * <p>
721      * When both <tt>lockedMonitors</tt> and <tt>lockedSynchronizers</tt>
722      * parameters are <tt>false</tt>, it is equivalent to calling:
723      * <blockquote><pre>
724      *     {@link #getThreadInfo(long[], int)  getThreadInfo(ids, Integer.MAX_VALUE)}
725      * </pre></blockquote>
726      *
727      * <p>
728      * This method is designed for troubleshooting use, but not for
729      * synchronization control.  It might be an expensive operation.
730      *
731      * <p>
732      * <b>MBeanServer access</b>:<br>
733      * The mapped type of <tt>ThreadInfo</tt> is
734      * <tt>CompositeData</tt> with attributes as specified in the
735      * {@link ThreadInfo#from ThreadInfo.from} method.
736      *
737      * @param  ids an array of thread IDs.
738      * @param  lockedMonitors if <tt>true</tt>, retrieves all locked monitors.
739      * @param  lockedSynchronizers if <tt>true</tt>, retrieves all locked
740      *             ownable synchronizers.
741      *
742      * @return an array of the {@link ThreadInfo} objects, each containing
743      * information about a thread whose ID is in the corresponding
744      * element of the input array of IDs.
745      *
746      * @throws java.lang.SecurityException if a security manager
747      *         exists and the caller does not have
748      *         ManagementPermission("monitor").
749      * @throws java.lang.UnsupportedOperationException
750      *         <ul>
751      *           <li>if <tt>lockedMonitors</tt> is <tt>true</tt> but
752      *               the Java virtual machine does not support monitoring
753      *               of {@linkplain #isObjectMonitorUsageSupported
754      *               object monitor usage}; or</li>
755      *           <li>if <tt>lockedSynchronizers</tt> is <tt>true</tt> but
756      *               the Java virtual machine does not support monitoring
757      *               of {@linkplain #isSynchronizerUsageSupported
758      *               ownable synchronizer usage}.</li>
759      *         </ul>
760      *
761      * @see #isObjectMonitorUsageSupported
762      * @see #isSynchronizerUsageSupported
763      *
764      * @since 1.6
765      */
766     public ThreadInfo[] getThreadInfo(long[] ids, boolean lockedMonitors, boolean lockedSynchronizers);
767 
768     /**
769      * Returns the thread info for all live threads with stack trace
770      * and synchronization information.
771      * Some threads included in the returned array
772      * may have been terminated when this method returns.
773      *
774      * <p>
775      * This method returns an array of {@link ThreadInfo} objects
776      * as specified in the {@link #getThreadInfo(long[], boolean, boolean)}
777      * method.
778      *
779      * @param  lockedMonitors if <tt>true</tt>, dump all locked monitors.
780      * @param  lockedSynchronizers if <tt>true</tt>, dump all locked
781      *             ownable synchronizers.
782      *
783      * @return an array of {@link ThreadInfo} for all live threads.
784      *
785      * @throws java.lang.SecurityException if a security manager
786      *         exists and the caller does not have
787      *         ManagementPermission("monitor").
788      * @throws java.lang.UnsupportedOperationException
789      *         <ul>
790      *           <li>if <tt>lockedMonitors</tt> is <tt>true</tt> but
791      *               the Java virtual machine does not support monitoring
792      *               of {@linkplain #isObjectMonitorUsageSupported
793      *               object monitor usage}; or</li>
794      *           <li>if <tt>lockedSynchronizers</tt> is <tt>true</tt> but
795      *               the Java virtual machine does not support monitoring
796      *               of {@linkplain #isSynchronizerUsageSupported
797      *               ownable synchronizer usage}.</li>
798      *         </ul>
799      *
800      * @see #isObjectMonitorUsageSupported
801      * @see #isSynchronizerUsageSupported
802      *
803      * @since 1.6
804      */
805     public ThreadInfo[] dumpAllThreads(boolean lockedMonitors, boolean lockedSynchronizers);
806 }