Package org.apache.commons.lang3

Class ThreadUtils

java.lang.Object

org.apache.commons.lang3.ThreadUtils

public class ThreadUtils
extends Object

Helpers for Thread and ThreadGroup.

#ThreadSafe#

Since:

3.5

See Also:

• Thread
• ThreadGroup

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ThreadUtils.NamePredicate	Deprecated. Use a Predicate.
static interface	ThreadUtils.ThreadGroupPredicate	Deprecated. Use a Predicate.
static class	ThreadUtils.ThreadIdPredicate	Deprecated. Use a Predicate.
static interface	ThreadUtils.ThreadPredicate	Deprecated. Use a Predicate.

Field Summary

Fields

Modifier and Type	Field	Description
static final org.apache.commons.lang3.ThreadUtils.AlwaysTruePredicate	ALWAYS_TRUE_PREDICATE	Deprecated. Use a Predicate.

Constructor Summary

Constructors

Constructor	Description
ThreadUtils()	Deprecated. TODO Make private in 4.0.

Method Summary

Modifier and Type	Method	Description
static Thread	findThreadById(long threadId)	Finds the active thread with the specified id.
static Thread	findThreadById(long threadId, String threadGroupName)	Finds the active thread with the specified id if it belongs to a thread group with the specified group name.
static Thread	findThreadById(long threadId, ThreadGroup threadGroup)	Finds the active thread with the specified id if it belongs to the specified thread group.
static Collection<ThreadGroup>	findThreadGroups(ThreadGroup threadGroup, boolean recurse, Predicate<ThreadGroup> predicate)	Finds all active thread groups which match the given predicate and which is a subgroup of the given thread group (or one of its subgroups).
static Collection<ThreadGroup>	findThreadGroups(ThreadGroup threadGroup, boolean recurse, ThreadUtils.ThreadGroupPredicate predicate)	Deprecated. Use findThreadGroups(ThreadGroup, boolean, Predicate).
static Collection<ThreadGroup>	findThreadGroups(Predicate<ThreadGroup> predicate)	Finds all active thread groups which match the given predicate.
static Collection<ThreadGroup>	findThreadGroups(ThreadUtils.ThreadGroupPredicate predicate)	Deprecated. Use findThreadGroups(Predicate).
static Collection<ThreadGroup>	findThreadGroupsByName(String threadGroupName)	Finds active thread groups with the specified group name.
static Collection<Thread>	findThreads(ThreadGroup threadGroup, boolean recurse, Predicate<Thread> predicate)	Finds all active threads which match the given predicate and which belongs to the given thread group (or one of its subgroups).
static Collection<Thread>	findThreads(ThreadGroup threadGroup, boolean recurse, ThreadUtils.ThreadPredicate predicate)	Deprecated. Use findThreads(ThreadGroup, boolean, Predicate).
static Collection<Thread>	findThreads(Predicate<Thread> predicate)	Finds all active threads which match the given predicate.
static Collection<Thread>	findThreads(ThreadUtils.ThreadPredicate predicate)	Deprecated. Use findThreads(Predicate).
static Collection<Thread>	findThreadsByName(String threadName)	Finds active threads with the specified name.
static Collection<Thread>	findThreadsByName(String threadName, String threadGroupName)	Finds active threads with the specified name if they belong to a thread group with the specified group name.
static Collection<Thread>	findThreadsByName(String threadName, ThreadGroup threadGroup)	Finds active threads with the specified name if they belong to a specified thread group.
static Collection<ThreadGroup>	getAllThreadGroups()	Gets all active thread groups excluding the system thread group (A thread group is active if it has been not destroyed).
static Collection<Thread>	getAllThreads()	Gets all active threads (A thread is active if it has been started and has not yet died).
static ThreadGroup	getSystemThreadGroup()	Gets the system thread group (sometimes also referred as "root thread group").
static void	join(Thread thread, Duration duration)	Waits for the given thread to die for the given duration.
static void	sleep(Duration duration)	Sleeps the current thread for the given duration.
static void	sleepQuietly(Duration duration)	Sleeps for the given duration while ignoring InterruptedException.

Methods inherited from class java.lang.Object

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

Field Details

ALWAYS_TRUE_PREDICATE

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

Deprecated.

Use a Predicate.

Predicate which always returns true.

Constructor Details

ThreadUtils

@Deprecated
public ThreadUtils()

Deprecated.

TODO Make private in 4.0.

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 Details

findThreadById

public static 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:

IllegalArgumentException - if the specified id is zero or negative

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreadById

public static Thread findThreadById(long threadId,
 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:

NullPointerException - if the group name is null

IllegalArgumentException - if the specified id is zero or negative

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreadById

public static Thread findThreadById(long threadId,
 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:

NullPointerException - if threadGroup == null

IllegalArgumentException - if the specified id is zero or negative

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreadGroups

public static Collection<ThreadGroup> findThreadGroups(Predicate<ThreadGroup> predicate)

Finds all active thread groups which match the given predicate.

Parameters:

predicate - the predicate

Returns:

An unmodifiable Collection of active thread groups matching the given predicate

Throws:

NullPointerException - if the predicate is null

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

Since:

3.13.0

findThreadGroups

public static Collection<ThreadGroup> findThreadGroups(ThreadGroup threadGroup,
 boolean recurse,
 Predicate<ThreadGroup> predicate)

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

Parameters:

threadGroup - the thread group

recurse - if true then evaluate the predicate recursively on all thread groups in all subgroups of the given group

predicate - the predicate

Returns:

An unmodifiable Collection of active thread groups which match the given predicate and which is a subgroup of the given thread group

Throws:

NullPointerException - if the given group or predicate is null

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

Since:

3.13.0

findThreadGroups

@Deprecated
public static Collection<ThreadGroup> findThreadGroups(ThreadGroup threadGroup,
 boolean recurse,
 ThreadUtils.ThreadGroupPredicate predicate)

Deprecated.

Use findThreadGroups(ThreadGroup, boolean, Predicate).

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

Parameters:

threadGroup - the thread group

recurse - if true then evaluate the predicate recursively on all thread groups in all subgroups of the given group

predicate - the predicate

Returns:

An unmodifiable Collection of active thread groups which match the given predicate and which is a subgroup of the given thread group

Throws:

NullPointerException - if the given group or predicate is null

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreadGroups

@Deprecated
public static Collection<ThreadGroup> findThreadGroups(ThreadUtils.ThreadGroupPredicate predicate)

Deprecated.

Use findThreadGroups(Predicate).

Finds all active thread groups which match the given predicate.

Parameters:

predicate - the predicate

Returns:

An unmodifiable Collection of active thread groups matching the given predicate

Throws:

NullPointerException - if the predicate is null

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreadGroupsByName

public static Collection<ThreadGroup> findThreadGroupsByName(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:

NullPointerException - if group name is null

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreads

public static Collection<Thread> findThreads(Predicate<Thread> predicate)

Finds all active threads which match the given predicate.

Parameters:

predicate - the predicate

Returns:

An unmodifiable Collection of active threads matching the given predicate

Throws:

NullPointerException - if the predicate is null

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

Since:

3.13.0

findThreads

public static Collection<Thread> findThreads(ThreadGroup threadGroup,
 boolean recurse,
 Predicate<Thread> predicate)

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

Parameters:

threadGroup - 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:

NullPointerException - if the given group or predicate is null

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

Since:

3.13.0

findThreads

@Deprecated
public static Collection<Thread> findThreads(ThreadGroup threadGroup,
 boolean recurse,
 ThreadUtils.ThreadPredicate predicate)

Deprecated.

Use findThreads(ThreadGroup, boolean, Predicate).

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

Parameters:

threadGroup - 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:

NullPointerException - if the given group or predicate is null

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreads

@Deprecated
public static Collection<Thread> findThreads(ThreadUtils.ThreadPredicate predicate)

Deprecated.

Use findThreads(Predicate).

Finds all active threads which match the given predicate.

Parameters:

predicate - the predicate

Returns:

An unmodifiable Collection of active threads matching the given predicate

Throws:

NullPointerException - if the predicate is null

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreadsByName

public static Collection<Thread> findThreadsByName(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:

NullPointerException - if the specified name is null

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreadsByName

public static Collection<Thread> findThreadsByName(String threadName,
 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:

NullPointerException - if the specified thread name or group name is null

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

findThreadsByName

public static Collection<Thread> findThreadsByName(String threadName,
 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:

NullPointerException - if the specified thread name or group is null

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

getAllThreadGroups

public static Collection<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:

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

getAllThreads

public static Collection<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:

SecurityException - if the current thread cannot access the system thread group

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

getSystemThreadGroup

public static ThreadGroup getSystemThreadGroup()

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

This method returns null if this thread has died (been stopped).

Returns:

the system thread group

Throws:

SecurityException - if the current thread cannot modify thread groups from this thread's thread group up to the system thread group

join

public static void join(Thread thread,
 Duration duration)
                 throws InterruptedException

Waits for the given thread to die for the given duration. Implemented using Thread.join(long, int).

Parameters:

thread - The thread to join.

duration - How long to wait.

Throws:

InterruptedException - if any thread has interrupted the current thread.

Since:

3.12.0

See Also:

• Thread.join(long, int)

sleep

public static void sleep(Duration duration)
                  throws InterruptedException

Sleeps the current thread for the given duration. Implemented using Thread.sleep(long, int).

Parameters:

duration - How long to sleep.

Throws:

InterruptedException - if any thread has interrupted the current thread.

Since:

3.12.0

See Also:

• Thread.sleep(long, int)

sleepQuietly

public static void sleepQuietly(Duration duration)

Sleeps for the given duration while ignoring InterruptedException.

The sleep duration may be shorter than duration if we catch a InterruptedException.

Parameters:

duration - the length of time to sleep.

Since:

3.13.0