Module org.microbean.interceptor

Package org.microbean.interceptor

Class Chain

java.lang.Object

org.microbean.interceptor.Chain

All Implemented Interfaces:

InvocationContext, Callable<Object>

@Deprecated(forRemoval=true)
public class Chain
extends Object
implements Callable<Object>, InvocationContext

Deprecated, for removal: This API element is subject to removal in a future version.

See Interceptions.

A Callable InvocationContext implementation representing the interception of a constructor, method, or lifecycle event.

Author:

Laird Nelson

See Also:

proceed()

Constructor Summary

Constructors

Constructor	Description
Chain()	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new Chain primarily for testing purposes.
Chain(List<? extends InterceptorMethod> interceptorMethods, Constructor<?> terminalConstructor)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new Chain for around-construct interceptions.
Chain(List<? extends InterceptorMethod> interceptorMethods, Constructor<?> terminalConstructor, Supplier<? extends Object[]> argumentsSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new Chain for around-construct interceptions.
Chain(List<? extends InterceptorMethod> interceptorMethods, Function<? super Object[],?> terminalFunction, Supplier<? extends Object[]> argumentsSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new Chain for around-construct interceptions.
Chain(List<? extends InterceptorMethod> interceptorMethods, Supplier<?> targetSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new Chain for lifecycle method interceptions.
Chain(List<? extends InterceptorMethod> interceptorMethods, Supplier<?> targetSupplier, Method terminalMethod)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new Chain for around-invoke interceptions.
Chain(List<? extends InterceptorMethod> interceptorMethods, Supplier<?> targetSupplier, Method terminalMethod, Supplier<? extends Object[]> argumentsSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new Chain for around-invoke interceptions.
Chain(List<? extends InterceptorMethod> interceptorMethods, Supplier<?> targetSupplier, Function<? super Object[],?> terminalFunction, boolean setTarget, Supplier<? extends Object[]> argumentsSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates a new Chain for around-construct or around-invoke interceptions.

Method Summary

Modifier and Type	Method	Description
Object	call()	Deprecated, for removal: This API element is subject to removal in a future version. Invokes the proceed() method and returns its result.
Constructor<?>	getConstructor()	Deprecated, for removal: This API element is subject to removal in a future version. Returns the Constructor being intercepted, if available, or null.
Map<String,Object>	getContextData()	Deprecated, for removal: This API element is subject to removal in a future version. Returns the context data Map shared by the current invocation.
Method	getMethod()	Deprecated, for removal: This API element is subject to removal in a future version. Returns the Method being intercepted, if available, or null.
Object[]	getParameters()	Deprecated, for removal: This API element is subject to removal in a future version. Returns any arguments in effect for the current interception.
Object	getTarget()	Deprecated, for removal: This API element is subject to removal in a future version. Returns the target instance, if available, or null.
Object	getTimer()	Deprecated, for removal: This API element is subject to removal in a future version. Returns the timer, if available, or null.
Object	proceed()	Deprecated, for removal: This API element is subject to removal in a future version. Applies the next interception in this Chain, or calls the terminal function, and returns the result of the interception, which may be null.
void	setParameters(Object[] arguments)	Deprecated, for removal: This API element is subject to removal in a future version. Sets arguments to be in effect for the current interception.
void	setTarget(Object target)	Deprecated. This really shouldn't be needed as part of the public API.
static Function<Object[],Object>	terminalFunctionOf(MethodHandle receiverlessMethodHandle)	Deprecated, for removal: This API element is subject to removal in a future version. Creates and returns a Function encapsulating the supplied MethodHandle.
static Function<Object[],Object>	terminalFunctionOf(MethodHandle mh, Supplier<?> receiverSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates and returns a Function encapsulating the supplied MethodHandle.
static Function<Object[],Object>	terminalFunctionOf(Constructor<?> c)	Deprecated, for removal: This API element is subject to removal in a future version. Creates and returns a Function encapsulating the supplied Constructor.
static Function<Object[],Object>	terminalFunctionOf(Method staticMethod)	Deprecated, for removal: This API element is subject to removal in a future version. Creates and returns a Function encapsulating the supplied static Method.
static Function<Object[],Object>	terminalFunctionOf(Method m, Supplier<?> receiverSupplier)	Deprecated, for removal: This API element is subject to removal in a future version. Creates and returns a Function encapsulating the supplied Method.
static void	validate(Class<?>[] parameterTypes, Object[] arguments)	Deprecated, for removal: This API element is subject to removal in a future version. 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

Methods inherited from interface jakarta.interceptor.InvocationContext

getInterceptorBinding, getInterceptorBindings, getInterceptorBindings

Constructor Detail

Chain

public Chain()

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new Chain primarily for testing purposes.

The resulting Chain will return null from the following methods:

• call()
• getConstructor()
• getMethod()
• getTimer()
• getTarget()
• proceed()

Chain

public Chain(List<? extends InterceptorMethod> interceptorMethods,
             Supplier<?> targetSupplier)

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new Chain for lifecycle method interceptions.

The resulting Chain will return null from the following methods:

• getConstructor()
• getMethod()
• getTimer()

Parameters:

interceptorMethods - a List of InterceptorMethods; may, rather uselessly, be null

targetSupplier - a Supplier of the target instance; may, rather uselessly, be null

Chain

public Chain(List<? extends InterceptorMethod> interceptorMethods,
             Constructor<?> terminalConstructor)
      throws IllegalAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new Chain for around-construct interceptions.

The resulting Chain will return null from the following methods:

• getMethod()
• getTarget()
• getTimer()

Parameters:

interceptorMethods - a List of InterceptorMethods; may, rather uselessly, be null

terminalConstructor - the Constructor being intercepted; must not be null

Throws:

NullPointerException - if terminalConstructor is null

IllegalAccessException - if unreflecting fails

Chain

public Chain(List<? extends InterceptorMethod> interceptorMethods,
             Constructor<?> terminalConstructor,
             Supplier<? extends Object[]> argumentsSupplier)
      throws IllegalAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new Chain for around-construct interceptions.

The resulting Chain will return null from the following methods:

• getMethod()
• getTimer()

Parameters:

interceptorMethods - a List of InterceptorMethods; may, rather uselessly, be null

terminalConstructor - the Constructor being intercepted; must not be null

argumentsSupplier - a Supplier supplying the arguments for the Constructor; may be null

Throws:

NullPointerException - if terminalConstructor is null

IllegalAccessException - if unreflecting fails

Chain

public Chain(List<? extends InterceptorMethod> interceptorMethods,
             Function<? super Object[],?> terminalFunction,
             Supplier<? extends Object[]> argumentsSupplier)

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new Chain for around-construct interceptions.

The resulting Chain will return null from the following methods:

• getConstructor()
• getMethod()
• getTimer()

Parameters:

interceptorMethods - a List of InterceptorMethods; may, rather uselessly, be null

terminalFunction - the terminal Function to intercept; must not be null

argumentsSupplier - a Supplier supplying the arguments for the terminal Function; may be null

Throws:

NullPointerException - if terminalFunction is null

Chain

public Chain(List<? extends InterceptorMethod> interceptorMethods,
             Supplier<?> targetSupplier,
             Method terminalMethod)
      throws IllegalAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new Chain for around-invoke interceptions.

The resulting Chain will return null from the following methods:

• getConstructor()
• getTimer()

Parameters:

interceptorMethods - a List of InterceptorMethods; may, rather uselessly, be null

targetSupplier - a Supplier of the target instance; may, rather uselessly, be null

terminalMethod - the Method to intercept; must not be null

Throws:

NullPointerException - if terminalMethod is null

IllegalAccessException - if unreflecting fails

Chain

public Chain(List<? extends InterceptorMethod> interceptorMethods,
             Supplier<?> targetSupplier,
             Method terminalMethod,
             Supplier<? extends Object[]> argumentsSupplier)
      throws IllegalAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new Chain for around-invoke interceptions.

The resulting Chain will return null from the following methods:

• getConstructor()
• getTimer()

Parameters:

interceptorMethods - a List of InterceptorMethods; may, rather uselessly, be null

targetSupplier - a Supplier of the target instance; may, rather uselessly, be null

terminalMethod - the Method to intercept; must not be null

argumentsSupplier - a Supplier supplying the arguments for the Method; may be null

Throws:

NullPointerException - if terminalMethod is null

IllegalAccessException - if unreflecting fails

Chain

public Chain(List<? extends InterceptorMethod> interceptorMethods,
             Supplier<?> targetSupplier,
             Function<? super Object[],?> terminalFunction,
             boolean setTarget,
             Supplier<? extends Object[]> argumentsSupplier)

Deprecated, for removal: This API element is subject to removal in a future version.

Creates a new Chain for around-construct or around-invoke interceptions.

The resulting Chain will return null from the following methods:

• getConstructor()
• getMethod()
• getTimer()

Parameters:

interceptorMethods - a List of InterceptorMethods; may, rather uselessly, be null

targetSupplier - a Supplier of the target instance; may, rather uselessly, be null

terminalFunction - the terminal Function to intercept; must not be null

setTarget - whether the supplied terminalFunction is effectively a constructor

argumentsSupplier - a Supplier supplying the arguments for the terminal Function; may be null

Throws:

NullPointerException - if terminalFunction is null

Method Detail

getConstructor

public final Constructor<?> getConstructor()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns the Constructor being intercepted, if available, or null.

Specified by:

getConstructor in interface InvocationContext

Returns:

the Constructor being intercepted, if available, or null

getContextData

public final Map<String,Object> getContextData()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns the context data Map shared by the current invocation.

Specified by:

getContextData in interface InvocationContext

Returns:

the context data Map shared by the current invocation; never null

See Also:

InvocationContext.getContextData()

getMethod

public final Method getMethod()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns the Method being intercepted, if available, or null.

Specified by:

getMethod in interface InvocationContext

Returns:

the Method being intercepted, if available, or null

getParameters

public final Object[] getParameters()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns any arguments in effect for the current interception.

For historical reasons, the Jakarta Interceptors specification refers, incorrectly, to arguments as "parameters".

Specified by:

getParameters in interface InvocationContext

Returns:

any arguments in effect for the current interception; never null

Throws:

IllegalStateException - if invoked within a lifecycle callback method that is not an AroundConstruct callback

See Also:

setParameters(Object[])

getTarget

public final Object getTarget()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns the target instance, if available, or null.

Specified by:

getTarget in interface InvocationContext

Returns:

the target instance, if available, or null

setTarget

@Deprecated
public final void setTarget(Object target)

Deprecated.

This really shouldn't be needed as part of the public API.

Sets the target instance to be the supplied target.

Parameters:

target - the target instance; must not be null

Throws:

NullPointerException - if target is null

See Also:

getTarget()

getTimer

public final Object getTimer()

Deprecated, for removal: This API element is subject to removal in a future version.

Returns the timer, if available, or null.

Specified by:

getTimer in interface InvocationContext

Returns:

the timer, if available, or null

call

public final Object call()
                  throws Exception

Deprecated, for removal: This API element is subject to removal in a future version.

Invokes the proceed() method and returns its result.

Specified by:

call in interface Callable<Object>

Returns:

the result of invoking the proceed() method, which may be null

Throws:

Exception - if an error occurs

See Also:

proceed()

proceed

public Object proceed()
               throws Exception

Deprecated, for removal: This API element is subject to removal in a future version.

Applies the next interception in this Chain, or calls the terminal function, and returns the result of the interception, which may be null.

Overrides must not call call() or an infinite loop will result.

Specified by:

proceed in interface InvocationContext

Returns:

the result of proceeding, which may be null

Throws:

Exception - if an error occurs

setParameters

public final void setParameters(Object[] arguments)

Deprecated, for removal: This API element is subject to removal in a future version.

Sets arguments to be in effect for the current interception.

For historical reasons, the Jakarta Interceptors specification refers, incorrectly, to arguments as "parameters".

Specified by:

setParameters in interface InvocationContext

Parameters:

arguments - the arguments; may be null

Throws:

IllegalArgumentException - if the arguments are invalid

IllegalStateException - if invoked within a lifecycle callback method that is not an AroundConstruct callback

See Also:

getParameters()

terminalFunctionOf

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

Deprecated, for removal: This API element is subject to removal in a future version.

Creates and returns a Function encapsulating the supplied Constructor.

Parameters:

c - a Constructor; must not be null

Returns:

a Function encapsulating the supplied Constructor; never null

Throws:

NullPointerException - if c is null

IllegalAccessException - if unreflecting fails

terminalFunctionOf

public static final Function<Object[],Object> terminalFunctionOf(Method staticMethod)
                                                                throws IllegalAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

Creates and returns a Function encapsulating the supplied static Method.

Parameters:

staticMethod - a static Method; must not be null

Returns:

a Function encapsulating the supplied static Method; never null

Throws:

NullPointerException - if staticMethod is null

IllegalAccessException - if unreflecting fails

terminalFunctionOf

public static final Function<Object[],Object> terminalFunctionOf(Method m,
                                                                       Supplier<?> receiverSupplier)
                                                                throws IllegalAccessException

Deprecated, for removal: This API element is subject to removal in a future version.

Creates and returns a Function encapsulating the supplied Method.

Parameters:

m - a Method; must not be null. If m is a virtual method, then the supplied receiverSupplier will be used to supply its receiver

receiverSupplier - a Supplier of the receiver for the supplied Method; may be null in which case the supplied Method must be static

Returns:

a Function encapsulating the supplied Method; never null

Throws:

NullPointerException - if m is null

IllegalAccessException - if unreflecting fails

terminalFunctionOf

public static final Function<Object[],Object> terminalFunctionOf(MethodHandle receiverlessMethodHandle)

Deprecated, for removal: This API element is subject to removal in a future version.

Creates and returns a Function encapsulating the supplied MethodHandle.

Parameters:

receiverlessMethodHandle - a MethodHandle; must not be null; must be receiverless or bound to a receiver already.

Returns:

a Function encapsulating the supplied MethodHandle; never null

Throws:

NullPointerException - if receiverlessMethodHandle is null

terminalFunctionOf

public static final Function<Object[],Object> terminalFunctionOf(MethodHandle mh,
                                                                       Supplier<?> receiverSupplier)

Deprecated, for removal: This API element is subject to removal in a future version.

Creates and returns a Function encapsulating the supplied MethodHandle.

Parameters:

mh - a MethodHandle; must not be null. If mh is a MethodHandle requiring a receiver, then the supplied receiverSupplier, if non-null, will be used to supply its receiver

receiverSupplier - a Supplier of the receiver for the supplied MethodHandle; may be null in which case the supplied MethodHandle must be receiverless

Returns:

a Function encapsulating the supplied MethodHandle; never null

Throws:

NullPointerException - if mh is null

validate

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

Deprecated, for removal: This API element is subject to removal in a future version.

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 not every element of the supplied arguments array can be assigned to a reference bearing the corresponding Class drawn from the supplied parameterTypes array

See Also:

setParameters(Object[])