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 /**
034 * Classes implementing this interface can configured to intercept invocations.
035 * These classes are constructed by their (typically implicit) {@code public}
036 * accessible constructor. Example (A) shows how to implement an interceptor
037 * using this interface. A more sophisticated interceptor is listed at example
038 * (B).
039 *
040 * <p><h3>Examples</h3>
041 * <b>(A)</b> Example of an interceptor implementing the {@code Interceptor}
042 * interface:
043 * <pre>
044 * public class ExampleInterceptor implements Interceptor {
045 *
046 * public Object intercept(InvocationContext ctx) throws Exception {
047 * try {
048 * // Run code before the invocation...
049 * return ctx.proceed();
050 * } finally {
051 * // Run code after the invocation...
052 * }
053 * }
054 * }
055 * </pre>
056 *
057 * <b>(B)</b> Example of an interceptor that provides some very basic fail-over
058 * functionality:
059 * <pre>
060 * public class ExampleInterceptor implements Interceptor {
061 *
062 * public Object intercept(InvocationContext ctx) throws Exception {
063 * try {
064 * return ctx.proceed();
065 * } catch (IOException e) {
066 * // Re-establish the connection.
067 * ((Foo) ctx.getTarget()).connect();
068 *
069 * // Retry invocation.
070 * return ctx.proceed();
071 * }
072 * }
073 * }
074 * </pre>
075 * </p>
076 *
077 * <p>A more powerful alternative to this interface is the {@link AroundInvoke}
078 * annotation.</p>
079 *
080 * @see AroundInvoke
081 * @see Interceptors
082 * @author Leon van Zantvoort
083 */
084 public interface Interceptor {
085
086 /**
087 * <p>Intercepts an invocation.</p>
088 */
089 Object intercept(InvocationContext ctx) throws Exception;
090 }