InvocationContext源码翻译

package javax.interceptor;

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

/**
 * 目的：调用上下文信息控制调用链的行为
 * 
 * <p>公开有关被截获的调用和操作的上下文信息，这些信息使拦截器方法能够控制调用链的行为。如：
 * 		@AroundInvoke
 *   	public Object logInvocation(InvocationContext ctx) throws Exception {
 *      	String class = ctx.getMethod().getDeclaringClass().getName();
 *      	String method = ctx.getMethod().getName();
 *      	Logger.global.entering(class, method, ctx.getParameters());
 *      	try {
 *         		Object result = ctx.proceed();
 *         		Logger.global.exiting(class, method, result);
 *         		return result;
 *      	} catch (Exception e) {
 *         		Logger.global.throwing(class, method, e);
 *         		throw e;
 *      	}
 *
 *   	}
 * @author TCM
 * @create 2017年11月10日上午10:00:32
 * @since  Interceptors 1.0
 */
public interface InvocationContext {

    /**
     * 返回目标实例。
     * 对于{@link AroundConstruct}生命周期回调拦截方法，
     * 如果在proceed()方法前调用，则getTarget()方法返回null。
     */
    public Object getTarget();

    /**
     * 返回与目标类的超时方法调用相关联的计时器对象，
     * 或是
     * 对方法和声明周期回调拦截器方法返回null值。
     * 例如：返回与EJB组件超时关联的对象{@link javax.ejb.Timer}。
     * @return 定时器对象或null值
     * @since Interceptors 1.1
     */
    public Object getTimer();

    /**
     * 返回调用拦截器的目标类的方法。
     * 生命周期回调拦截器中没有对应的生命周期回调方法，则：getMethod返回null。
     * @return 返回目标类的方法或null值
     */
    public Method getMethod();

    /**
     * 返回调用拦截器的目标类的构造函数。
     * 对于{@link AroundConstruct}拦截器，则返回目标类的构造函数；
     * 对于其他的拦截器，则返回null。
     */
    public Constructor<?> getConstructor();

    /**
     * 返回传递给目标类的方法或构造函数的参数值。
     * 如果{@link #setParameters}已被调用，则getParameters返回已经设置参数的值。
     * @exception java.lang.IllegalStateException
     */
    public Object[] getParameters();
    
    /**
     * 设置传递给目标类的方法或构造函数的参数值。
     * @exception java.lang.IllegalStateException
     * @exception java.lang.IllegalArgumentException
     */
    public void setParameters(Object[] params);

    /**
     * 允许拦截器通过调用链中的另一个拦截器，
     * 业务方法和/或webservices上下文来检索或更新与调用相关联的数据。
     * 如果由于在Web服务端点上调用而调用拦截器，
     * 则返回的值将是javax.xml.rpc.handler.MessageContext的实例。
     * Enables an interceptor to retrieve or update the data associated with 
     * the invocation by another interceptor, business method,and/or webservices 
     * context in the invocation chain.  If interceptors are invoked as a result
     * of the invocation on a web service endpoint, the returned value will be 
     * an instance of javax.xml.rpc.handler.MessageContext
     * 
     * @return 与调用或生命周期回调相关联的上下文数据。若果没有上下文数据，则返回空的map
     */
    public Map<String, Object> getContextData();

    /**
     * 继续到拦截器链中的下一个拦截器。
     * 对于around-invoke或around-timeout拦截器方法，
     * 		调用链中最后一个拦截器方法将导致调用目标类方法。
     * 对于AroundConstruct生命周期回调拦截器方法，
     * 		调用链中的最后一个拦截器方法会导致创建目标实例。
     * 对于所有其他生命周期回调拦截器方法，
     * 		如果在目标类上没有定义回调方法，则在链中最后一个拦截器方法中的继续调用是no-op
     * 
     * <p>返回调用的下一个方法的结果，如果方法返回类型为void，则返回null值。
     * 
     * @return 调用链中的下一个方法
     */
    public Object proceed() throws Exception;

}