Package org.apache.commons.lang3

## Class ThreadUtils

- java.lang.Object
- - org.apache.commons.lang3.ThreadUtils

    public class ThreadUtils
    extends java.lang.Object

Helpers for `java.lang.Thread` and `java.lang.ThreadGroup`.

#ThreadSafe#

Since:
  3.5
See Also:
  `Thread`, `ThreadGroup`

### Nested Class Summary

Nested Classes
`static class` `ThreadUtils.NamePredicate` A predicate implementation which matches a thread or threadgroup name.
`static interface` `ThreadUtils.ThreadGroupPredicate` A predicate for selecting threadgroups.
`static class` `ThreadUtils.ThreadIdPredicate` A predicate implementation which matches a thread id.
`static interface` `ThreadUtils.ThreadPredicate` A predicate for selecting threads.

### Field Summary

Fields
`static org.apache.commons.lang3.ThreadUtils.AlwaysTruePredicate` `ALWAYS_TRUE_PREDICATE` Predicate which always returns true.

### Constructor Summary

Constructors
`ThreadUtils()` ThreadUtils instances should NOT be constructed in standard programming.

### Method Summary

All Methods Static Methods Concrete Methods
`static java.lang.Thread` `findThreadById​(long threadId)` Finds the active thread with the specified id.
`static java.lang.Thread` `findThreadById​(long threadId, java.lang.String threadGroupName)` Finds the active thread with the specified id if it belongs to a thread group with the specified group name.
`static java.lang.Thread` `findThreadById​(long threadId, java.lang.ThreadGroup threadGroup)` Finds the active thread with the specified id if it belongs to the specified thread group.
`static java.util.Collection<java.lang.ThreadGroup>` `findThreadGroups​(java.lang.ThreadGroup group, boolean recurse, ThreadUtils.ThreadGroupPredicate predicate)` Select all active threadgroups which match the given predicate and which is a subgroup of the given thread group (or one of its subgroups).
`static java.util.Collection<java.lang.ThreadGroup>` `findThreadGroups​(ThreadUtils.ThreadGroupPredicate predicate)` Select all active threadgroups which match the given predicate.
`static java.util.Collection<java.lang.ThreadGroup>` `findThreadGroupsByName​(java.lang.String threadGroupName)` Finds active thread groups with the specified group name.
`static java.util.Collection<java.lang.Thread>` `findThreads​(java.lang.ThreadGroup group, boolean recurse, ThreadUtils.ThreadPredicate predicate)` Select all active threads which match the given predicate and which belongs to the given thread group (or one of its subgroups).
`static java.util.Collection<java.lang.Thread>` `findThreads​(ThreadUtils.ThreadPredicate predicate)` Select all active threads which match the given predicate.
`static java.util.Collection<java.lang.Thread>` `findThreadsByName​(java.lang.String threadName)` Finds active threads with the specified name.
`static java.util.Collection<java.lang.Thread>` `findThreadsByName​(java.lang.String threadName, java.lang.String threadGroupName)` Finds active threads with the specified name if they belong to a thread group with the specified group name.
`static java.util.Collection<java.lang.Thread>` `findThreadsByName​(java.lang.String threadName, java.lang.ThreadGroup threadGroup)` Finds active threads with the specified name if they belong to a specified thread group.
`static java.util.Collection<java.lang.ThreadGroup>` `getAllThreadGroups()` Gets all active thread groups excluding the system thread group (A thread group is active if it has been not destroyed).
`static java.util.Collection<java.lang.Thread>` `getAllThreads()` Gets all active threads (A thread is active if it has been started and has not yet died).
`static java.lang.ThreadGroup` `getSystemThreadGroup()` Gets the system thread group (sometimes also referred as "root thread group").

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Field Detail

#### ALWAYS_TRUE_PREDICATE

    public static final org.apache.commons.lang3.ThreadUtils.AlwaysTruePredicate ALWAYS_TRUE_PREDICATE

Predicate which always returns true.

### Constructor Detail

#### ThreadUtils

    public ThreadUtils()

ThreadUtils instances should NOT be constructed in standard programming. Instead, the class should be used as `ThreadUtils.getAllThreads()`

This constructor is public to permit tools that require a JavaBean instance to operate.

### Method Detail

#### findThreadById

    public static java.lang.Thread findThreadById​(long threadId,
                                                  java.lang.ThreadGroup threadGroup)

Finds the active thread with the specified id if it belongs to the specified thread group.

Parameters:
  `threadId` - The thread id
  `threadGroup` - The thread group
Returns:
  The thread which belongs to a specified thread group and the thread's id match the specified id. `null` is returned if no such thread exists
Throws:
  `java.lang.IllegalArgumentException` - if the specified id is zero or negative or the group is null
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreadById

    public static java.lang.Thread findThreadById​(long threadId,
                                                  java.lang.String threadGroupName)

Finds the active thread with the specified id if it belongs to a thread group with the specified group name.

Parameters:
  `threadId` - The thread id
  `threadGroupName` - The thread group name
Returns:
  The threads which belongs to a thread group with the specified group name and the thread's id match the specified id. `null` is returned if no such thread exists
Throws:
  `java.lang.IllegalArgumentException` - if the specified id is zero or negative or the group name is null
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreadsByName

    public static java.util.Collection<java.lang.Thread> findThreadsByName​(java.lang.String threadName,
                                                                           java.lang.ThreadGroup threadGroup)

Finds active threads with the specified name if they belong to a specified thread group.

Parameters:
  `threadName` - The thread name
  `threadGroup` - The thread group
Returns:
  The threads which belongs to a thread group and the thread's name match the specified name, An empty collection is returned if no such thread exists. The collection returned is always unmodifiable.
Throws:
  `java.lang.IllegalArgumentException` - if the specified thread name or group is null
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreadsByName

    public static java.util.Collection<java.lang.Thread> findThreadsByName​(java.lang.String threadName,
                                                                           java.lang.String threadGroupName)

Finds active threads with the specified name if they belong to a thread group with the specified group name.

Parameters:
  `threadName` - The thread name
  `threadGroupName` - The thread group name
Returns:
  The threads which belongs to a thread group with the specified group name and the thread's name match the specified name, An empty collection is returned if no such thread exists. The collection returned is always unmodifiable.
Throws:
  `java.lang.IllegalArgumentException` - if the specified thread name or group name is null
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreadGroupsByName

    public static java.util.Collection<java.lang.ThreadGroup> findThreadGroupsByName​(java.lang.String threadGroupName)

Finds active thread groups with the specified group name.

Parameters:
  `threadGroupName` - The thread group name
Returns:
  the thread groups with the specified group name or an empty collection if no such thread group exists. The collection returned is always unmodifiable.
Throws:
  `java.lang.IllegalArgumentException` - if group name is null
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### getAllThreadGroups

    public static java.util.Collection<java.lang.ThreadGroup> getAllThreadGroups()

Gets all active thread groups excluding the system thread group (A thread group is active if it has been not destroyed).

Returns:
  all thread groups excluding the system thread group. The collection returned is always unmodifiable.
Throws:
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### getSystemThreadGroup

    public static java.lang.ThreadGroup getSystemThreadGroup()

Gets the system thread group (sometimes also referred as "root thread group").

Returns:
  the system thread group
Throws:
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### getAllThreads

    public static java.util.Collection<java.lang.Thread> getAllThreads()

Gets all active threads (A thread is active if it has been started and has not yet died).

Returns:
  all active threads. The collection returned is always unmodifiable.
Throws:
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreadsByName

    public static java.util.Collection<java.lang.Thread> findThreadsByName​(java.lang.String threadName)

Finds active threads with the specified name.

Parameters:
  `threadName` - The thread name
Returns:
  The threads with the specified name or an empty collection if no such thread exists. The collection returned is always unmodifiable.
Throws:
  `java.lang.IllegalArgumentException` - if the specified name is null
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreadById

    public static java.lang.Thread findThreadById​(long threadId)

Finds the active thread with the specified id.

Parameters:
  `threadId` - The thread id
Returns:
  The thread with the specified id or `null` if no such thread exists
Throws:
  `java.lang.IllegalArgumentException` - if the specified id is zero or negative
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreads

    public static java.util.Collection<java.lang.Thread> findThreads​(ThreadUtils.ThreadPredicate predicate)

Select all active threads which match the given predicate.

Parameters:
  `predicate` - the predicate
Returns:
  An unmodifiable `Collection` of active threads matching the given predicate
Throws:
  `java.lang.IllegalArgumentException` - if the predicate is null
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreadGroups

    public static java.util.Collection<java.lang.ThreadGroup> findThreadGroups​(ThreadUtils.ThreadGroupPredicate predicate)

Select all active threadgroups which match the given predicate.

Parameters:
  `predicate` - the predicate
Returns:
  An unmodifiable `Collection` of active threadgroups matching the given predicate
Throws:
  `java.lang.IllegalArgumentException` - if the predicate is null
  `java.lang.SecurityException` - if the current thread cannot access the system thread group
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreads

    public static java.util.Collection<java.lang.Thread> findThreads​(java.lang.ThreadGroup group,
                                                                     boolean recurse,
                                                                     ThreadUtils.ThreadPredicate predicate)

Select all active threads which match the given predicate and which belongs to the given thread group (or one of its subgroups).

Parameters:
  `group` - the thread group
  `recurse` - if `true` then evaluate the predicate recursively on all threads in all subgroups of the given group
  `predicate` - the predicate
Returns:
  An unmodifiable `Collection` of active threads which match the given predicate and which belongs to the given thread group
Throws:
  `java.lang.IllegalArgumentException` - if the given group or predicate is null
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

#### findThreadGroups

    public static java.util.Collection<java.lang.ThreadGroup> findThreadGroups​(java.lang.ThreadGroup group,
                                                                               boolean recurse,
                                                                               ThreadUtils.ThreadGroupPredicate predicate)

Select all active threadgroups which match the given predicate and which is a subgroup of the given thread group (or one of its subgroups).

Parameters:
  `group` - the thread group
  `recurse` - if `true` then evaluate the predicate recursively on all threadgroups in all subgroups of the given group
  `predicate` - the predicate
Returns:
  An unmodifiable `Collection` of active threadgroups which match the given predicate and which is a subgroup of the given thread group
Throws:
  `java.lang.IllegalArgumentException` - if the given group or predicate is null
  `java.lang.SecurityException` - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group