001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */
017:
018: package java.lang.management;
019:
020: /**
021: * <p>
022: * <code>ThreadMXBean</code> is an interface used by the management
023: * system to access thread-related properties.
024: * </p>
025: * <p>
026: * <code>ObjectName</code>: java.lang:type=Threading
027: * </p>
028: *
029: * @since 1.5
030: */
031: public interface ThreadMXBean {
032:
033: /**
034: * <p>
035: * Finds cycles of threads that are in deadlock waiting to acquire and
036: * object monitor.
037: * </p>
038: *
039: * @return An array of thread IDs of deadlocked.
040: * @throws SecurityException if caller doesn't have
041: * <code>ManagementPermission("monitor")</code>.
042: * @see Thread#getId()
043: */
044: long[] findMonitorDeadlockedThreads();
045:
046: /**
047: * <p>
048: * The ID of all currently live threads.
049: * </p>
050: *
051: * @return An array of thread IDs.
052: * @throws SecurityException if caller doesn't have
053: * <code>ManagementPermission("monitor")</code>.
054: * @see Thread#getId()
055: */
056: long[] getAllThreadIds();
057:
058: /**
059: * <p>
060: * The total CPU time (in nanoseconds) for the current thread. This is
061: * convenience method for {@link #getThreadCpuTime(long) getThreadCpuTime}<code>(Thread.currentThread().getId());</code>.
062: * </p>
063: *
064: * @return The total CPU time for the current thread.
065: * @throws UnsupportedOperationException if this is not supported.
066: */
067: long getCurrentThreadCpuTime();
068:
069: /**
070: * <p>
071: * The total user time (in nanoseconds) for the current thread. This is
072: * convenience method for {@link #getThreadUserTime(long) getThreadUserTime}<code>(Thread.currentThread().getId());</code>.
073: * </p>
074: *
075: * @return The total user time for the current thread.
076: * @throws UnsupportedOperationException if this is not supported.
077: */
078: long getCurrentThreadUserTime();
079:
080: /**
081: * <p>
082: * The current number of live daemon threads.
083: * </p>
084: *
085: * @return The number of daemon threads.
086: */
087: int getDaemonThreadCount();
088:
089: /**
090: * <p>
091: * The peak number of live threads since JVM start or the last reset.
092: * </p>
093: *
094: * @return The peak number of threads.
095: * @see #resetPeakThreadCount()
096: */
097: int getPeakThreadCount();
098:
099: /**
100: * <p>
101: * The current number of live threads (daemon and non-daemon).
102: * </p>
103: *
104: * @return The number of threads.
105: */
106: int getThreadCount();
107:
108: /**
109: * <p>
110: * The total CPU time (in nanoseconds) for the given thread.
111: * </p>
112: *
113: * @param id The ID of the thread to get the CPU time for.
114: * @return The total CPU time for the current thread or -1 if the thread is
115: * not alive or measurement is not enabled.
116: * @throws IllegalArgumentException if <code>id</code> is less than or
117: * equal to 0.
118: * @throws UnsupportedOperationException if this is not supported.
119: */
120: long getThreadCpuTime(long id);
121:
122: /**
123: * <p>
124: * The thread information for the given thread with a stack trace depth of
125: * zero.
126: * </p>
127: *
128: * @param id The ID of the thread to get information for.
129: * @return A {@link ThreadInfo} instance representing the information of the
130: * given thread or <code>null</code> if the thread is not alive or
131: * doesn't exist.
132: * @throws IllegalArgumentException if <code>id</code> is less than or
133: * equal to 0.
134: * @throws SecurityException if caller doesn't have
135: * <code>ManagementPermission("monitor")</code>.
136: */
137: ThreadInfo getThreadInfo(long id);
138:
139: /**
140: * <p>
141: * The thread information for the given threads with a stack trace depth of
142: * zero.
143: * </p>
144: *
145: * @param ids An array of IDs of the threads to get information for.
146: * @return An array of {@link ThreadInfo} instance representing the
147: * information of the given threads.
148: * @throws IllegalArgumentException if and element in <code>ids</code> is
149: * less than or equal to 0.
150: * @throws SecurityException if caller doesn't have
151: * <code>ManagementPermission("monitor")</code>.
152: */
153: ThreadInfo[] getThreadInfo(long[] ids);
154:
155: /**
156: * <p>
157: * The thread information for the given threads, which is qualified by a
158: * maximum stack trace depth.
159: * </p>
160: *
161: * @param ids An array of IDs of the threads to get information for.
162: * @param maxDepth The maximum depth of the stack trace to return in the
163: * {@link ThreadInfo}. If zero, then an empty array is stored. If
164: * {@link Integer#MAX_VALUE}, then the entire stack trace is
165: * returned.
166: * @return An array of {@link ThreadInfo} instance representing the
167: * information of the given threads.
168: * @throws IllegalArgumentException if and element in <code>ids</code> is
169: * less than or equal to 0.
170: * @throws SecurityException if caller doesn't have
171: * <code>ManagementPermission("monitor")</code>.
172: */
173: ThreadInfo[] getThreadInfo(long[] ids, int maxDepth);
174:
175: /**
176: * <p>
177: * The thread information for the given thread with a stack trace depth of
178: * zero.
179: * </p>
180: *
181: * @param id The ID of the thread to get information for.
182: * @param maxDepth The maximum depth of the stack trace to return in the
183: * {@link ThreadInfo}. If zero, then an empty array is stored. If
184: * {@link Integer#MAX_VALUE}, then the entire stack trace is
185: * returned.
186: * @return A {@link ThreadInfo} instance representing the information of the
187: * given thread or <code>null</code> if the thread is not alive or
188: * doesn't exist.
189: * @throws IllegalArgumentException if <code>id</code> is less than or
190: * equal to 0.
191: * @throws SecurityException if caller doesn't have
192: * <code>ManagementPermission("monitor")</code>.
193: */
194: ThreadInfo getThreadInfo(long id, int maxDepth);
195:
196: /**
197: * <p>
198: * The total user time (in nanoseconds) for the given thread.
199: * </p>
200: *
201: * @param id The ID of the thread to get the user time for.
202: * @return The total user time for the current thread or -1 if the thread is
203: * not alive or measurement is not enabled.
204: * @throws IllegalArgumentException if <code>id</code> is less than or
205: * equal to 0.
206: * @throws UnsupportedOperationException if this is not supported.
207: */
208: long getThreadUserTime(long id);
209:
210: /**
211: * <p>
212: * The total number of threads that have been created and started within the
213: * JVM.
214: * </p>
215: *
216: * @return The total number of created and started threads.
217: */
218: long getTotalStartedThreadCount();
219:
220: /**
221: * <p>
222: * Indicates whether or not current thread CPU time monitoring is supported.
223: * </p>
224: *
225: * @return <code>true</code> if supported, otherwise <code>false</code>.
226: */
227: boolean isCurrentThreadCpuTimeSupported();
228:
229: /**
230: * <p>
231: * Indicates whether or not thread contention monitoring is enabled.
232: * </p>
233: *
234: * @return <code>true</code> if enabled, otherwise <code>false</code>.
235: */
236: boolean isThreadContentionMonitoringEnabled();
237:
238: /**
239: * <p>
240: * Indicates whether or not thread contention monitoring is supported.
241: * </p>
242: *
243: * @return <code>true</code> if supported, otherwise <code>false</code>.
244: */
245: boolean isThreadContentionMonitoringSupported();
246:
247: /**
248: * <p>
249: * Indicates whether or not thread CPU time monitoring is enabled.
250: * </p>
251: *
252: * @return <code>true</code> if enabled, otherwise <code>false</code>.
253: */
254: boolean isThreadCpuTimeEnabled();
255:
256: /**
257: * <p>
258: * Indicates whether or not thread CPU time monitoring is supported.
259: * </p>
260: *
261: * @return <code>true</code> if supported, otherwise <code>false</code>.
262: */
263: boolean isThreadCpuTimeSupported();
264:
265: /**
266: * <p>
267: * Resets the peak thread count to the current thread count.
268: * </p>
269: *
270: * @throws SecurityException if caller doesn't have
271: * <code>ManagementPermission("control")</code>.
272: */
273: void resetPeakThreadCount();
274:
275: /**
276: * <p>
277: * Enables or disables thread contention monitoring.
278: * </p>
279: *
280: * @param enable <code>true</code> to enable, <code>false</code> to
281: * disable.
282: * @throws UnsupportedOperationException if this is not supported.
283: * @throws SecurityException if caller doesn't have
284: * <code>ManagementPermission("control")</code>.
285: * @see #isThreadContentionMonitoringSupported()
286: */
287: void setThreadContentionMonitoringEnabled(boolean enable);
288:
289: /**
290: * <p>
291: * Enables or disables thread CPU time monitoring.
292: * </p>
293: *
294: * @param enable <code>true</code> to enable, <code>false</code> to
295: * disable.
296: * @throws UnsupportedOperationException if this is not supported.
297: * @throws SecurityException if caller doesn't have
298: * <code>ManagementPermission("control")</code>.
299: * @see #isThreadCpuTimeSupported()
300: */
301: void setThreadCpuTimeEnabled(boolean enable);
302: }
|