co.mindus.ip2location

Interface IVirtualThreadFactory

All Superinterfaces:

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 IVirtualThreadFactory
extends IThreadFactory

Factory class for creating Virtual threads used by IP2Location components on Java 21 or better.

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

Usage Example

 IP2LocationService service = new IP2LocationService.Builder()
     .downloadToken("your-token")
     .threadFactory(new VirtualThreadFactory(task, name, daemon))
     .build();
 

Author:

Christopher Mindus

See Also:

IP2LocationService.Builder.threadFactory(IThreadFactory)

Method Summary

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

Methods inherited from interface co.mindus.ip2location.IThreadFactory

withExceptionHandler

Method Detail

newThread

default Thread newThread(Runnable task,
                         String name)

Creates a new Virtual 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.

The implementations does not respect the daemon-mode as it doesn't exist for Virtual Threads: all Virtual Threads are daemon threads.

Calling this executes the following code, effectively creating a new daemon Virtual Tread.

   return newThread(task,name,true);
 

Parameters:

task - The runnable task to execute

name - The suggested name for the thread (e.g., "IP2Location-Updater")

Returns:

A new, unstarted virtual thread configured to run the task, as a daemon thread.

newThread

Thread newThread(Runnable task,
                 String name,
                 boolean daemon)

Creates a new Virtual 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.

The Virtual Thread Implementations cannot respect the daemon parameter, as all Virtual Threads are daemon threads, thus threads are used for background tasks that should not prevent JVM shutdown.

Do not use non-daemon threads if they are used for critical operations that must complete.

Specified by:

newThread in interface IThreadFactory

Parameters:

task - The runnable task to execute

name - The suggested name for the thread (e.g., "IP2Location-Updater")

daemon - This daemon variable is not used with Virtual Threads as only daemon thread states exist in the Virtual Threads world.

NOTE: this parameter will be ignored, like if it was set to true.

Returns:

A new, unstarted virtual thread configured to run the task

defaultFactory

static IVirtualThreadFactory 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;
 }
 

Specified by:

defaultFactory in interface IThreadFactory

Returns:

A thread factory that creates standard platform threads

defaultWithExceptionHandler

static IVirtualThreadFactory 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.

Specified by:

defaultWithExceptionHandler in interface IThreadFactory

Parameters:

handler - The exception handler to install.

Returns:

A new factory that wraps the delegate with exception handling

withExceptionHandler

static IVirtualThreadFactory withExceptionHandler(IVirtualThreadFactory 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