ch.sourcepond.utils.mdcwrapper.api

Interface MdcWrapper

public interface MdcWrapper

Simple facade to wrap different objects into SLF4J MDC aware proxies. See the logback documentation for more information about mapped diagnostic context.

A proxy created through this facade will wrap any Runnable or Callable task into a MDC-aware wrapper. This wrapper will copy the MDC context from the master thread (the thread which committed the task to the executor) to the pool-thread (the thread which executes the task) before the original task is actually executed. After execution, the wrapper will cleanup the MDC context on the pool-thread to avoid memory leaks.

Collections and one-dimensional arrays of tasks are also taken into account when wrapping is performed.

Method Summary

Methods

Modifier and Type	Method and Description
<V> Callable<V>	wrap(Callable<V> pCallable) Wraps the Callable specified into a MDC-aware proxy.
Runnable	wrap(Runnable pRunnable) Wraps the Runnable specified into a MDC-aware proxy.
<T extends Executor> T	wrap(T pExecutor, Class<T> pInterface) Wraps the executor specified into a MDC-aware proxy using the executor interface specified.
ThreadFactory	wrap(ThreadFactory pThreadFactory) Wraps the ThreadFactory specified into a MDC-aware proxy.

Method Detail

wrap

<T extends Executor> T wrap(T pExecutor,
                          Class<T> pInterface)

Wraps the executor specified into a MDC-aware proxy using the executor interface specified. If the executor specified is already a MDC-aware proxy, it will be returned without being wrapped.

The created executor proxy will wrap tasks passed to its methods in following cases:

• The method takes one or more Runnable as argument.
• The method takes one or more Callable as argument.
• The method takes one or more Collection of Runnable as argument.
• The method takes one or more Collection of Callable as argument.
• The method takes one or more one-dimensional array of Runnable as argument.
• The method takes one or more one-dimensional array of Callable as argument.

If a collection of tasks is passed to a method on the proxy, all contained tasks will be wrapped and added to a new collection. The new collection will eventually passed to the according method on the original executor. If an array of tasks is passed to a method on the proxy, all contained tasks will be wrapped. The wrapped tasks will replace the original tasks in the parameter array. In contrast to collections, parameter arrays will not be duplicated.

Type Parameters:

T - Type of the executor to be wrapped, must be assignable from Executor.

Parameters:

pExecutor - Executor to be proxied, must not be null

pInterface - The interface of the executor; will be used to create the proxy, must not be null

Returns:

New MDC-aware executor proxy, never null

Throws:

NullPointerException - Thrown, if either argument is null

IllegalArgumentException - Thrown, if the class specified is not an interface.

wrap

ThreadFactory wrap(ThreadFactory pThreadFactory)

Wraps the ThreadFactory specified into a MDC-aware proxy. Every task passed to the ThreadFactory.newThread(Runnable) method on the proxy will be wrapped before it is eventually passed to the original thread-factory specified. If the thread-factory specified is already a MDC-aware proxy, it will be returned without being wrapped.

Parameters:

pThreadFactory - Thread-factory to be proxied, must not be null

Returns:

New MDC-aware thread-factory proxy, never null

wrap

Runnable wrap(Runnable pRunnable)

Wraps the Runnable specified into a MDC-aware proxy. During construction of the proxy, the MDC context of the current thread will be copied and stored. When the Runnable.run() method on the proxy is called, the copied MDC context will be set on the executing thread. After the method finishes, the MDC context on the executing thread will be cleared. If the runnable specified is already MDC-aware, it will be returned without being wrapped.

This method should only be used when the resulting proxy is executed in a thread-pool, or, with a thread which was not created by the caller thread. If the executor thread is created by the caller thread, it's an unnecessary overhead to copy the MDC context because it's already inherited from the caller.

Parameters:

pRunnable - Runnable to be proxied, must not be null

Returns:

New MDC-aware Runnable proxy, never null

wrap

<V> Callable<V> wrap(Callable<V> pCallable)

Wraps the Callable specified into a MDC-aware proxy. During construction of the proxy, the MDC context of the current thread will be copied and stored. When the Callable.call() method on the proxy is called, the copied MDC context will be set on the executing thread. After the method finishes, the MDC context on the executing thread will be cleared. If the callable specified is already MDC-aware, it will be returned without being wrapped.

This method should only be used when the resulting proxy is executed in a thread-pool, or, with a thread which was not created by the caller thread. If the executor thread is created by the caller thread, it's an unnecessary overhead to copy the MDC context because it's already inherited from the caller.

Parameters:

pCallable - Callable to be proxied, must not be null

Returns:

New MDC-aware Callable proxy, never null