001 /*
002 * ============================================================================
003 * GNU Lesser General Public License
004 * ============================================================================
005 *
006 * Beanlet - JSE Application Container.
007 * Copyright (C) 2006 Leon van Zantvoort
008 *
009 * This library is free software; you can redistribute it and/or
010 * modify it under the terms of the GNU Lesser General Public
011 * License as published by the Free Software Foundation; either
012 * version 2.1 of the License, or (at your option) any later version.
013 *
014 * This library is distributed in the hope that it will be useful,
015 * but WITHOUT ANY WARRANTY; without even the implied warranty of
016 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
017 * Lesser General Public License for more details.
018 *
019 * You should have received a copy of the GNU Lesser General Public
020 * License along with this library; if not, write to the Free Software
021 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
022 *
023 * Leon van Zantvoort
024 * 243 Acalanes Drive #11
025 * Sunnyvale, CA 94086
026 * USA
027 *
028 * zantvoort@users.sourceforge.net
029 * http://beanlet.org
030 */
031 package org.beanlet;
032
033 import java.lang.reflect.Method;
034 import java.util.Map;
035
036 /**
037 * <p>Allow interceptor and lifecycle methods to control the behavior of the
038 * invocation chain.</p>
039 *
040 * <p>The same {@code InvocationContext} instance is passed to each interceptor
041 * method for a given business method or lifecycle event interception. This
042 * allows an interceptor to save information in the context data property of the
043 * {@code InvocationContext} that can be subsequently retrieved in other
044 * interceptors as means to pass contextual data between interceptors. The
045 * contextual data is not shareable across separate business method invocations
046 * or lifecycle callback events. The lifecycle of the {@code InvocationContext}
047 * is instance otherwise unspecified.</p>
048 *
049 * @author Leon van Zantvoort
050 */
051 public interface InvocationContext {
052
053 /**
054 * Returns a map that can be used to pass contextual data between
055 * interceptors of the interceptor chain.
056 */
057 Map<String, Object> getContextData();
058
059 /**
060 * The method that is intercepted. This method does not return {@code null},
061 * since only methods can be intercepted.
062 * @throws BeanletStateException if this method is called from an lifecycle
063 * interceptor.
064 */
065 Method getMethod() throws BeanletStateException;
066
067 /**
068 * Returns the parameter of the current invocation.
069 * @throws BeanletStateException if this method is called from an lifecycle
070 * interceptor.
071 */
072 Object[] getParameters() throws BeanletStateException;
073
074 /**
075 * Allows the caller to modify the parameters of the current invocation.
076 * @throws BeanletStateException if this method is called from an lifecycle
077 * interceptor.
078 */
079 void setParameters(Object[] parameters) throws BeanletStateException;
080
081 /**
082 * Invokes the next interceptor in the chain, or, when called from the last
083 * interceptor, the business method. Interceptor methods must always call
084 * {@code InvocationContext.proceed()} or nu subsequent interceptor methods
085 * or lifecycle callback methods or business method will be invoked. The
086 * {@code proceed} method returns the result of the next method invoked. If
087 * a method returns {@code void}, {@code proceed} returns {@code null}. For
088 * lifecycle callback methods, if there is no callback method defined on the
089 * beanlet class, the invocation of {@code proceed} in the last method in
090 * the chain is a on-op, and {@code null} is returned. If there is more than
091 * one such method, the invocation of {@code proceed} causes the application
092 * container to execute those methods in order.
093 *
094 * @return result of next method.
095 */
096 Object proceed() throws Exception;
097
098 /**
099 * Returns the underlying object.
100 *
101 * @return the underlying object.
102 */
103 Object getTarget();
104 }