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 final InterceptionFunction	ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods, MethodHandles.Lookup lookup, 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 final InterceptionFunction	ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods, MethodHandles.Lookup lookup, 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 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().
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().
static final InterceptionFunction	ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods, MethodHandles.Lookup lookup, 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 final InterceptionFunction	ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods, MethodHandles.Lookup lookup, 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 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().
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().
static final Runnable	ofLifecycleEvent(Collection<? extends InterceptorMethod> interceptorMethods, Supplier<?> targetBootstrap)	Returns a Runnable whose run() method will invoke all supplied InterceptorMethods in encounter order.
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.
static final BiFunction<Object,Object[],Object>	terminalBiFunctionOf(MethodHandle mh)	Creates and returns a BiFunction encapsulating the supplied MethodHandle.
static final BiFunction<Object,Object[],Object>	terminalBiFunctionOf(MethodHandles.Lookup lookup, Constructor<?> c)	Creates and returns a BiFunction encapsulating the supplied Constructor.
static final BiFunction<Object,Object[],Object>	terminalBiFunctionOf(MethodHandles.Lookup lookup, Method m)	Creates and returns a BiFunction encapsulating the supplied Method.
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.

Methods inherited from class java.lang.Object

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

Method Details

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,
 MethodHandles.Lookup lookup,
 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)

lookup - a MethodHandles.Lookup; must not be null

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

Returns:

an InterceptionFunction; never null

Throws:

NullPointerException - if lookup is null

IllegalAccessException - if unreflecting fails

ofConstruction

public static final InterceptionFunction ofConstruction(Collection<? extends InterceptorMethod> interceptorMethods,
 MethodHandles.Lookup lookup,
 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)

lookup - a MethodHandles.Lookup; must not be null

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:

NullPointerException - if lookup is null

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,
 MethodHandles.Lookup lookup,
 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)

lookup - a MethodHandles.Lookup; must not be null

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:

NullPointerException - if lookup is null

IllegalAccessException - if unreflecting fails

ofInvocation

public static final InterceptionFunction ofInvocation(Collection<? extends InterceptorMethod> interceptorMethods,
 MethodHandles.Lookup lookup,
 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)

lookup - a MethodHandles.Lookup; must not be null

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:

NullPointerException - if lookup is null

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(MethodHandles.Lookup lookup,
 Constructor<?> c)
                                                                     throws IllegalAccessException

Creates and returns a BiFunction encapsulating the supplied Constructor.

Parameters:

lookup - a MethodHandles.Lookup; must not be null

c - a Constructor; must not be null

Returns:

a BiFunction encapsulating the supplied Constructor; never null

Throws:

NullPointerException - if any argumebnt is null

IllegalAccessException - if unreflecting fails

terminalBiFunctionOf

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

Creates and returns a BiFunction encapsulating the supplied Method.

Parameters:

lookup - a MethodHandles.Lookup; must not be null

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