co.mindus.ip2location

Interface IThreadFactory

All Known Subinterfaces:

IVirtualThreadFactory

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 (Java 21+)

To use virtual threads, provide an implementation that calls Thread.ofVirtual().name(name).unstarted(task):

 IThreadFactory virtualFactory = (task, name, daemon) -> 
     Thread.ofVirtual().name(name).unstarted(task);
 

Platform Threads (Java 8+)

The defaultFactory() method provides a standard implementation that works with all Java versions:

 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:

IP2LocationService.Builder.threadFactory(IThreadFactory)

Method Summary

Modifier and Type	Method and Description
static IThreadFactory	defaultFactory() Returns the default thread factory implementation.
static IThreadFactory	defaultWithExceptionHandler(Thread.UncaughtExceptionHandler handler) Creates the default Virtual Thread factory with exception handling.
Thread	newThread(Runnable task, String name, boolean daemon) Creates a new thread for the specified task.
static IThreadFactory	withExceptionHandler(IThreadFactory delegate, Thread.UncaughtExceptionHandler handler) Creates a thread factory that wraps another factory with exception handling.

Method Detail

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. If the Java VM is 21 or better, the Virtual Threads co.mindus.ip2location.IVirtualThreadFactory will be used instead.

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