Module org.microbean.interceptor

Package org.microbean.interceptor

Class Interceptions

java.lang.Object

org.microbean.interceptor.Interceptions

public final class Interceptions
extends Object

A utility class that makes InterceptionFunctions and Runnables that intercept lifecycle events, constructions, and invocations of methods in accordance with the Jakarta Interceptors specification.

Author:

Laird Nelson

Method Summary

Modifier and Type	Method	Description
static InterceptionFunction	ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods, Constructor<?> constructor)	Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied Constructor's newInstance(Object...) method.
static InterceptionFunction	ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods, Constructor<?> constructor, Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)	Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied Constructor's newInstance(Object...) method.
static InterceptionFunction	ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods, BiFunction<? super Object,? super Object[],?> terminalBiFunction)	Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied BiFunction's apply(Object, Object[]) method with null (the return value of InvocationContext.getTarget(), which will always be null in this scenario) and the return value of an invocation of InvocationContext.getParameters().
static InterceptionFunction	ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods, BiFunction<? super Object,? super Object[],?> terminalBiFunction, Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)	Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied BiFunction's apply(Object Object[]) method with null (the return value of InvocationContext.getTarget(), which will always be null in this scenario) and the return value of an invocation of InvocationContext.getParameters().
static InterceptionFunction	ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods, Method method, Supplier<?> targetBootstrap)	Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied Method's invoke(Object, Object...) method with the return value of InvocationContext.getTarget(), and with the return value of InvocationContext.getParameters().
static InterceptionFunction	ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods, Method method, Supplier<?> targetBootstrap, Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)	Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied Method's invoke(Object, Object...) method with the return value of InvocationContext.getTarget(), and with the return value of InvocationContext.getParameters().
static InterceptionFunction	ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods, BiFunction<? super Object,? super Object[],?> terminalBiFunction, Supplier<?> targetBootstrap)	Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied BiFunction's apply(Object Object[]) method with the return value of InvocationContext.getTarget(), and with the return value of InvocationContext.getParameters().
static InterceptionFunction	ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods, BiFunction<? super Object,? super Object[],?> terminalBiFunction, Supplier<?> targetBootstrap, Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)	Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied BiFunction's apply(Object Object[]) method with the return value of InvocationContext.getTarget(), and with the return value of InvocationContext.getParameters().
static Runnable	ofLifecycleEvent(Collection<? extends InterceptorMethod> interceptorMethods, Supplier<?> targetBootstrap)	Returns a Runnable whose run() method will invoke all supplied InterceptorMethods in encounter order.
static Runnable	ofLifecycleEvent(Collection<? extends InterceptorMethod> interceptorMethods, Supplier<?> targetBootstrap, Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)	Returns a Runnable whose run() method will invoke all supplied InterceptorMethods in encounter order.
static BiFunction<Object,Object[],Object>	terminalBiFunctionOf(MethodHandle mh)	Creates and returns a BiFunction encapsulating the supplied MethodHandle.
static BiFunction<Object,Object[],Object>	terminalBiFunctionOf(Constructor<?> c)	Creates and returns a BiFunction encapsulating the supplied Constructor.
static BiFunction<Object,Object[],Object>	terminalBiFunctionOf(Method m)	Creates and returns a BiFunction encapsulating the supplied Method.
static void	validate(Class<?>[] parameterTypes, Object[] arguments)	A convenience method that ensures that every element of the supplied arguments array can be assigned to a reference bearing the corresponding Class drawn from the supplied parameterTypes array.

Methods inherited from class java.lang.Object

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

Method Detail

ofLifecycleEvent

public static final Runnable ofLifecycleEvent(Collection<? extends InterceptorMethod> interceptorMethods,
                                              Supplier<?> targetBootstrap)

Returns a Runnable whose run() method will invoke all supplied InterceptorMethods in encounter order.

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null in which case the returned Runnable's run() method will do nothing

targetBootstrap - a Supplier that will be called for the initial value to be returned by the first invocation of InvocationContext.getTarget(); may be null in which case the value too will be null

Returns:

a Runnable; never null

ofLifecycleEvent

public static final Runnable ofLifecycleEvent(Collection<? extends InterceptorMethod> interceptorMethods,
                                              Supplier<?> targetBootstrap,
                                              Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)

Returns a Runnable whose run() method will invoke all supplied InterceptorMethods in encounter order.

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null in which case the returned Runnable's run() method will do nothing

targetBootstrap - a Supplier that will be called for the initial value to be returned by the first invocation of InvocationContext.getTarget(); may be null in which case the value too will be null

interceptorBindingsBootstrap - a Supplier of a Set of Annotations that will be called for the value to be returned by the first invocation of InvocationContext.getInterceptorBindings(); may be null in which case the value will be an empty, immutable Set

Returns:

a Runnable; never null

ofConstruction

public static final InterceptionFunction ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods,
                                                        Constructor<?> constructor)
                                                 throws IllegalAccessException

Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied Constructor's newInstance(Object...) method.

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null (rather uselessly)

constructor - the Constructor to invoke; may be null (rather uselessly)

Returns:

an InterceptionFunction; never null

Throws:

IllegalAccessException - if unreflecting fails

ofConstruction

public static final InterceptionFunction ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods,
                                                        Constructor<?> constructor,
                                                        Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)
                                                 throws IllegalAccessException

Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied Constructor's newInstance(Object...) method.

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null (rather uselessly)

constructor - the Constructor to invoke; may be null (rather uselessly)

interceptorBindingsBootstrap - a Supplier of a Set of Annotations that will be called for the value to be returned by the first invocation of InvocationContext.getInterceptorBindings(); may be null in which case the value will be an empty, immutable Set

Returns:

an InterceptionFunction; never null

Throws:

IllegalAccessException - if unreflecting fails

ofConstruction

public static final InterceptionFunction ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods,
                                                        BiFunction<? super Object,? super Object[],?> terminalBiFunction)

Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied BiFunction's apply(Object, Object[]) method with null (the return value of InvocationContext.getTarget(), which will always be null in this scenario) and the return value of an invocation of InvocationContext.getParameters().

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null (rather uselessly)

terminalBiFunction - a BiFunction serving as a notional constructor that takes null, always, as its first argument, and the return value of an invocation of InvocationContext.getParameters() as its second argument, and returns a new instance; may be null (rather uselessly)

Returns:

an InterceptionFunction; never null

ofConstruction

public static final InterceptionFunction ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods,
                                                        BiFunction<? super Object,? super Object[],?> terminalBiFunction,
                                                        Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)

Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied BiFunction's apply(Object Object[]) method with null (the return value of InvocationContext.getTarget(), which will always be null in this scenario) and the return value of an invocation of InvocationContext.getParameters().

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null (rather uselessly)

terminalBiFunction - a BiFunction serving as a notional constructor that takes null, always, as its first argument, and the return value of an invocation of InvocationContext.getParameters() as its second argument, and returns a new instance; may be null (rather uselessly)

interceptorBindingsBootstrap - a Supplier of a Set of Annotations that will be called for the value to be returned by the first invocation of InvocationContext.getInterceptorBindings(); may be null in which case the value will be an empty, immutable Set

Returns:

an InterceptionFunction; never null

ofInvocation

public static final InterceptionFunction ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods,
                                                      Method method,
                                                      Supplier<?> targetBootstrap)
                                               throws IllegalAccessException

Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied Method's invoke(Object, Object...) method with the return value of InvocationContext.getTarget(), and with the return value of InvocationContext.getParameters().

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null (rather uselessly)

method - a Method encapsulating the invocation to be intercepted whose invoke(Object, Object...) method takes the return value of InvocationContext.getTarget() as its first argument, and the return value of InvocationContext.getParameters() spread out appropriately as its trailing arguments; may be null (rather uselessly)

targetBootstrap - a Supplier that will be called for the initial value to be returned by the first invocation of InvocationContext.getTarget(); may be null in which case the value too will be null

Returns:

an InterceptionFunction; never null

Throws:

IllegalAccessException - if unreflecting fails

ofInvocation

public static final InterceptionFunction ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods,
                                                      Method method,
                                                      Supplier<?> targetBootstrap,
                                                      Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)
                                               throws IllegalAccessException

Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied Method's invoke(Object, Object...) method with the return value of InvocationContext.getTarget(), and with the return value of InvocationContext.getParameters().

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null (rather uselessly)

method - a Method encapsulating the invocation to be intercepted whose invoke(Object, Object...) method takes the return value of InvocationContext.getTarget() as its first argument, and the return value of InvocationContext.getParameters() spread out appropriately as its trailing arguments; may be null (rather uselessly)

targetBootstrap - a Supplier that will be called for the initial value to be returned by the first invocation of InvocationContext.getTarget(); may be null in which case the value too will be null

interceptorBindingsBootstrap - a Supplier of a Set of Annotations that will be called for the value to be returned by the first invocation of InvocationContext.getInterceptorBindings(); may be null in which case the value will be an empty, immutable Set

Returns:

an InterceptionFunction; never null

Throws:

IllegalAccessException - if unreflecting fails

ofInvocation

public static final InterceptionFunction ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods,
                                                      BiFunction<? super Object,? super Object[],?> terminalBiFunction,
                                                      Supplier<?> targetBootstrap)

Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied BiFunction's apply(Object Object[]) method with the return value of InvocationContext.getTarget(), and with the return value of InvocationContext.getParameters().

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null (rather uselessly)

terminalBiFunction - a BiFunction encapsulating the invocation to be intercepted that takes the return value of InvocationContext.getTarget() as its first argument, and the return value of InvocationContext.getParameters() as its second argument; may be null (rather uselessly)

targetBootstrap - a Supplier that will be called for the initial value to be returned by the first invocation of InvocationContext.getTarget(); may be null in which case the value too will be null

Returns:

an InterceptionFunction; never null

ofInvocation

public static final InterceptionFunction ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods,
                                                      BiFunction<? super Object,? super Object[],?> terminalBiFunction,
                                                      Supplier<?> targetBootstrap,
                                                      Supplier<? extends Set<Annotation>> interceptorBindingsBootstrap)

Returns an InterceptionFunction whose apply(Object...) method will invoke all supplied InterceptorMethods in encounter order before invoking the supplied BiFunction's apply(Object Object[]) method with the return value of InvocationContext.getTarget(), and with the return value of InvocationContext.getParameters().

Parameters:

interceptorMethods - the InterceptorMethods to invoke; may be null (rather uselessly)

terminalBiFunction - a BiFunction encapsulating the invocation to be intercepted that takes the return value of InvocationContext.getTarget() as its first argument, and the return value of InvocationContext.getParameters() as its second argument; may be null (rather uselessly)

targetBootstrap - a Supplier that will be called for the initial value to be returned by the first invocation of InvocationContext.getTarget(); may be null in which case the value too will be null

interceptorBindingsBootstrap - a Supplier of a Set of Annotations that will be called for the value to be returned by the first invocation of InvocationContext.getInterceptorBindings(); may be null in which case the value will be an empty, immutable Set

Returns:

an InterceptionFunction; never null

terminalBiFunctionOf

public static final BiFunction<Object,Object[],Object> terminalBiFunctionOf(Constructor<?> c)
                                                                                 throws IllegalAccessException

Creates and returns a BiFunction encapsulating the supplied Constructor.

Parameters:

c - a Constructor; must not be null

Returns:

a BiFunction encapsulating the supplied Constructor; never null

Throws:

NullPointerException - if c is null

IllegalAccessException - if unreflecting fails

terminalBiFunctionOf

public static final BiFunction<Object,Object[],Object> terminalBiFunctionOf(Method m)
                                                                                 throws IllegalAccessException

Creates and returns a BiFunction encapsulating the supplied Method.

Parameters:

m - a Method; must not be null

Returns:

a BiFunction encapsulating the supplied Method; never null

Throws:

NullPointerException - if m is null

IllegalAccessException - if unreflecting fails

terminalBiFunctionOf

public static final BiFunction<Object,Object[],Object> terminalBiFunctionOf(MethodHandle mh)

Creates and returns a BiFunction encapsulating the supplied MethodHandle.

Parameters:

mh - a MethodHandle; must not be null

Returns:

a BiFunction encapsulating the supplied MethodHandle; never null

Throws:

NullPointerException - if mh is null

validate

public static final void validate(Class<?>[] parameterTypes,
                                  Object[] arguments)

A convenience method that ensures that every element of the supplied arguments array can be assigned to a reference bearing the corresponding Class drawn from the supplied parameterTypes array.

Boxing, unboxing and widening conversions are taken into consideration.

This method implements the logic implied, but nowhere actually specified, by the contract of InvocationContext.setParameters(Object[]).

Parameters:

parameterTypes - an array of Class instances; may be null; must not contain null elements or void.class; must have a length equal to that of the supplied arguments array

arguments - an array of Objects; may be null; must have a length equal to that of the supplied parameterTypes array

Throws:

IllegalArgumentException - if validation fails, i.e. if the length of parameterTypes is not equal to the length of arguments, or if an element of parameterTypes is null or void.class, or if not every element of the supplied arguments array can be assigned to a reference bearing the corresponding Class drawn from the supplied parameterTypes array