01 /*
02 * Copyright 2008-2014 the original author or authors.
03 *
04 * Licensed under the Apache License, Version 2.0 (the "License");
05 * you may not use this file except in compliance with the License.
06 * You may obtain a copy of the License at
07 *
08 * http://www.apache.org/licenses/LICENSE-2.0
09 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package griffon.core.controller;
17
18 import griffon.core.artifact.GriffonController;
19
20 import javax.annotation.Nonnull;
21 import java.lang.reflect.Method;
22
23 /**
24 * @author Andres Almiray
25 * @since 2.0.0
26 */
27 public interface ActionInterceptor {
28 String SUFFIX = "ActionInterceptor";
29
30 /**
31 * Inspect the action during the configuration phase.
32 * <p/>
33 * This is the perfect time to search for annotations or any other information
34 * required by the action. Interceptors have the option to cache such inspections
35 * and recall them during {@code before()}, {@code after()} and {@code exception()}.
36 *
37 * @param controller the controller that owns the action
38 * @param actionName the action's name
39 * @param method the method that represents the action itself
40 */
41 void configure(@Nonnull GriffonController controller, @Nonnull String actionName, @Nonnull Method method);
42
43 /**
44 * Called before an action is executed.
45 * <p/>
46 * Implementors have the choice of throwing an {@code AbortActionExecution} in
47 * order to signal that the action should not be invoked. In any case this method
48 * returns the arguments to be sent to the action, thus allowing the interceptor
49 * to modify the arguments as it deem necessary. Failure to return an appropriate
50 * value will most likely cause an error during the action's execution.
51 *
52 * @param controller the controller that owns the action
53 * @param actionName the action's name
54 * @param args the action's arguments
55 * @return arguments to be sent to the action
56 * @throws AbortActionExecution if action execution should be aborted.
57 */
58 @Nonnull
59 Object[] before(@Nonnull GriffonController controller, @Nonnull String actionName, @Nonnull Object[] args);
60
61 /**
62 * Called after the action has been aborted or executed, even if an exception
63 * occurred during execution.
64 * <p/>
65 *
66 * @param status a flag that indicates the execution status of the action
67 * @param controller the controller that owns the action
68 * @param actionName the action's name
69 * @param args the arguments sent to the action
70 */
71 void after(@Nonnull ActionExecutionStatus status, @Nonnull GriffonController controller, @Nonnull String actionName, @Nonnull Object[] args);
72
73 /**
74 * Called after the action has been executed when an exception occurred
75 * during execution.
76 * <p/>
77 * The exception will be rethrown by the ActionManager if is not handled by
78 * any interceptor.
79 *
80 * @param exception the exception thrown during the action's execution
81 * @param controller the controller that owns the action
82 * @param actionName the action's name
83 * @param args the arguments sent to the action during execution
84 * @return <code>true</code> if the exception was handled successfully,
85 * <code>false</code> otherwise.
86 */
87 boolean exception(@Nonnull Exception exception, @Nonnull GriffonController controller, @Nonnull String actionName, @Nonnull Object[] args);
88 }
|