javax.interceptor.InvocationContext Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of weld-servlet-shaded Show documentation
This jar bundles all the bits of Weld and CDI required for running in a Servlet container.
There is a newer version: 6.0.0.Beta4
package javax.interceptor;

import java.lang.reflect.Constructor;
import java.lang.reflect.Method;
import java.util.Map;

/**
 * Contextual information about a method invocation, along with methods to alter the invocation process
 * in various ways.
 */
public interface InvocationContext {

    /**
     * Get the target instance for this invocation.
     *
     * @return the target instance
     */
    Object getTarget();

    /**
     * Get the invoked method for this invocation.  If the invoked method is an {@link AroundInvoke @AroundInvoke} or
     * {@link AroundTimeout @AroundTimeout} interceptor method, the method of the target class is returned.  For
     * lifecycle callback interceptors (such as {@link javax.annotation.PostConstruct @PostConstruct} or {@link
     * javax.annotation.PreDestroy @PreDestroy}), {@code null} is returned.
     *
     * @return the invoked method, or {@code null} if none applies to the current invocation context
     */
    Method getMethod();

    /**
     * Returns the constructor of the target class for which the interceptor
     * was invoked.  For {@link AroundConstruct} interceptor, the constructor of the
     * target class is returned. For all other interceptors,
     * a null value is returned.
     *
     * @return the constructor, or a null value
     */
    public Constructor getConstructor();

    /**
     * Get the parameters of the method invocation (for method interceptors).
     *
     * @return the invoked method parameters
     *
     * @throws IllegalStateException if the current invocation context refers to a lifecycle callback invocation
     */
    Object[] getParameters() throws IllegalStateException;

    /**
     * Replace the parameters of the method invocation.
     *
     * @param params the new parameter values to use for the current invocation
     *
     * @throws IllegalStateException if the current invocation context refers to a lifecycle callback invocation
     * @throws IllegalArgumentException if the types or quantity of the method parameters does not match the method
     * declaration
     */
    void setParameters(Object[] params) throws IllegalStateException, IllegalArgumentException;

    /**
     * Returns the context data associated with this invocation or lifecycle callback.
     * 
     * If the current context is an invocation on a web service endpoint, the map returned will be the JAX-WS {@code
     * MessageContext}.  If there is no context data, an empty {@code Map} object will be returned.  Normally,
     * information stored in this map is available to subsequent interceptors in an interceptor chain, so this mechanism
     * may be used to pass information from one interceptor to the next.
     *
     * @return the context map
     */
    Map getContextData();

    /**
     * Get the timer associated with an {@link AroundTimeout @AroundTimeout} interceptor method.  When intercepting
     * an EJB component timeout, the returned type is {@link javax.ejb.Timer}.
     *
     * @return the timer object, or {@code null} if the invocation did not apply to a timeout method.
     */
    Object getTimer();

    /**
     * Proceed with the next stage of invocation processing.  Calling this method may cause another interceptor to be
     * invoked, or it may cause the final target object to be invoked.  The return value of this method is the result
     * of the subsequent invocation processing, or of the invocation itself.  Normally an interceptor will return this
     * value to its caller; however, it is also possible to return a different value.
     * 
     * If the intercepted method's return type is {@code void}, or if this is a lifecycle method interceptor, then
     * {@code null} is returned from this method, and should be returned by the interceptor as well.
     *
     * @return the result of subsequent interceptor method processing
     * @throws Exception if an exception is thrown by subsequent processing
     */
    Object proceed() throws Exception;
}