Interface IThreadFactory

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface IThreadFactory
Factory interface for creating threads used by IP2Location components.

This interface allows applications to control how threads are created for background tasks such as database downloads, scheduled updates, and asynchronous initialization. This is particularly useful for:

  • Using virtual threads in Java 21+ environments
  • Integrating with application server thread pools
  • Applying custom naming conventions
  • Setting thread priorities or other attributes
  • Monitoring and debugging thread usage

Virtual Threads

virtualFactory() creates virtual threads and is the builder's default:

IThreadFactory virtualFactory = IThreadFactory.virtualFactory();

Platform Threads

The defaultFactory() method provides a standard implementation that creates platform threads honouring the daemon flag:

IThreadFactory factory = IThreadFactory.defaultFactory();

Custom Thread Pool Integration

For application servers that manage their own thread pools:

IThreadFactory serverFactory = (task, name, daemon) -> {
    Thread t = myThreadPool.newThread(task);
    t.setName(name);
    t.setDaemon(daemon);
    return t;
};

Usage Example

IP2LocationService service = new IP2LocationService.Builder()
    .downloadToken("your-token")
    .threadFactory((task, name, daemon) -> {
        Thread t = new Thread(task, name);
        t.setDaemon(daemon);
        t.setPriority(Thread.MIN_PRIORITY);  // Low priority for background work
        return t;
    })
    .build();
Author:
Christopher Mindus
See Also:

  • Method Details

    • newThread

      Thread newThread(Runnable task, String name, boolean daemon)
      Creates a new thread for the specified task.

      The returned thread should be in the "new" state (not yet started). The caller is responsible for starting the thread.

      Implementations should respect the daemon parameter, as daemon threads are used for background tasks that should not prevent JVM shutdown, while non-daemon threads are used for critical operations that must complete.

      Parameters:
      task - The runnable task to execute
      name - The suggested name for the thread (e.g., "IP2Location-Updater")
      daemon - true if the thread should be a daemon thread, false for a user thread
      Returns:
      A new, unstarted thread configured to run the task

    • defaultFactory

      static IThreadFactory defaultFactory()
      Returns the default thread factory implementation.

      This factory creates standard platform threads with the specified name and daemon status. It is suitable for all Java versions (8+).

      The implementation is equivalent to:

      (task,name,daemon) -> {
  Thread t=new Thread(task,name);
  t.setDaemon(daemon);
  return t;
}
      Returns:
      A thread factory that creates standard platform threads.

    • virtualFactory

      static IThreadFactory virtualFactory()
      Returns a thread factory that creates virtual threads.

      This is the factory IP2LocationService.Builder uses when none is set. A virtual thread is always a daemon thread, so the daemon parameter of newThread(Runnable, String, boolean) is ignored: calling setDaemon(false) on a virtual thread throws IllegalArgumentException, which is why the flag is not forwarded. The thread name is applied.

      Returns:
      A thread factory that creates unstarted virtual threads.

    • defaultWithExceptionHandler

      static IThreadFactory defaultWithExceptionHandler(Thread.UncaughtExceptionHandler handler)
      Creates the default Virtual Thread factory with exception handling.

      The returned factory installs an uncaught exception handler on each created thread, ensuring that exceptions in background tasks are logged rather than silently swallowed.

      Parameters:
      handler - The exception handler to install.
      Returns:
      A new factory that wraps the delegate with exception handling

    • withExceptionHandler

      static IThreadFactory withExceptionHandler(IThreadFactory delegate, Thread.UncaughtExceptionHandler handler)
      Creates a thread factory that wraps another factory with exception handling.

      The returned factory installs an uncaught exception handler on each created thread, ensuring that exceptions in background tasks are logged rather than silently swallowed.

      Parameters:
      delegate - The underlying thread factory.
      handler - The exception handler to install.
      Returns:
      A new factory that wraps the delegate with exception handling