Package org.apache.commons.lang3

Class 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

    • Field Summary

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

    • Constructor Summary

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

    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      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 threadGroup, boolean recurse, java.util.function.Predicate<java.lang.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 java.util.Collection<java.lang.ThreadGroup> findThreadGroups​(java.lang.ThreadGroup threadGroup, boolean recurse, ThreadUtils.ThreadGroupPredicate predicate)
      Deprecated.
      Use findThreadGroups(ThreadGroup, boolean, Predicate).
      static java.util.Collection<java.lang.ThreadGroup> findThreadGroups​(java.util.function.Predicate<java.lang.ThreadGroup> predicate)
      Finds all active thread groups which match the given predicate.
      static java.util.Collection<java.lang.ThreadGroup> findThreadGroups​(ThreadUtils.ThreadGroupPredicate predicate)
      Deprecated.
      Use findThreadGroups(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 threadGroup, boolean recurse, java.util.function.Predicate<java.lang.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 java.util.Collection<java.lang.Thread> findThreads​(java.lang.ThreadGroup threadGroup, boolean recurse, ThreadUtils.ThreadPredicate predicate)
      Deprecated.
      Use findThreads(ThreadGroup, boolean, Predicate).
      static java.util.Collection<java.lang.Thread> findThreads​(java.util.function.Predicate<java.lang.Thread> predicate)
      Finds all active threads which match the given predicate.
      static java.util.Collection<java.lang.Thread> findThreads​(ThreadUtils.ThreadPredicate predicate)
      Deprecated.
      Use findThreads(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").
      static void join​(java.lang.Thread thread, java.time.Duration duration)
      Waits for the given thread to die for the given duration.
      static void sleep​(java.time.Duration duration)
      Sleeps the current thread for the given duration.
      static void sleepQuietly​(java.time.Duration duration)
      Sleeps for the given duration while ignoring InterruptedException.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • 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 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)
        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

      • 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.NullPointerException - if the group name is null
        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

      • 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.NullPointerException - if threadGroup == null
        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

      • findThreadGroups

        public static java.util.Collection<java.lang.ThreadGroup> findThreadGroups​(java.util.function.Predicate<java.lang.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:
        java.lang.NullPointerException - 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
        Since:
        3.13.0

      • findThreadGroups

        public static java.util.Collection<java.lang.ThreadGroup> findThreadGroups​(java.lang.ThreadGroup threadGroup,
                                                                           boolean recurse,
                                                                           java.util.function.Predicate<java.lang.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:
        java.lang.NullPointerException - 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
        Since:
        3.13.0

      • findThreadGroups

        @Deprecated
public static java.util.Collection<java.lang.ThreadGroup> findThreadGroups​(java.lang.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:
        java.lang.NullPointerException - 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

        @Deprecated
public static java.util.Collection<java.lang.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:
        java.lang.NullPointerException - 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

      • 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.NullPointerException - 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

      • findThreads

        public static java.util.Collection<java.lang.Thread> findThreads​(java.util.function.Predicate<java.lang.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:
        java.lang.NullPointerException - 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
        Since:
        3.13.0

      • findThreads

        public static java.util.Collection<java.lang.Thread> findThreads​(java.lang.ThreadGroup threadGroup,
                                                                 boolean recurse,
                                                                 java.util.function.Predicate<java.lang.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:
        java.lang.NullPointerException - 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
        Since:
        3.13.0

      • findThreads

        @Deprecated
public static java.util.Collection<java.lang.Thread> findThreads​(java.lang.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:
        java.lang.NullPointerException - 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

      • findThreads

        @Deprecated
public static java.util.Collection<java.lang.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:
        java.lang.NullPointerException - 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

      • 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.NullPointerException - 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

      • 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.NullPointerException - 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

      • 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.NullPointerException - 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

      • 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

      • 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

      • getSystemThreadGroup

        public static java.lang.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:
        java.lang.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​(java.lang.Thread thread,
                        java.time.Duration duration)
                 throws java.lang.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:
        java.lang.InterruptedException - if any thread has interrupted the current thread.
        Since:
        3.12.0
        See Also:
        Thread.join(long, int)

      • sleep

        public static void sleep​(java.time.Duration duration)
                  throws java.lang.InterruptedException
        Sleeps the current thread for the given duration. Implemented using Thread.sleep(long, int).
        Parameters:
        duration - How long to sleep.
        Throws:
        java.lang.InterruptedException - if any thread has interrupted the current thread.
        Since:
        3.12.0
        See Also:
        Thread.sleep(long, int)

      • sleepQuietly

        public static void sleepQuietly​(java.time.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