01 /*
02 * Copyright 2008-2017 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 javax.annotation.Nonnull;
19 import javax.annotation.Nullable;
20 import java.lang.reflect.Method;
21
22 /**
23 * @author Andres Almiray
24 * @since 2.1.0
25 */
26 public interface ActionHandler {
27 String SUFFIX = "ActionHandler";
28
29 /**
30 * Update the action's properties.
31 * <p/>
32 *
33 * @param action the action to be updated
34 */
35 void update(@Nonnull Action action);
36
37 /**
38 * Inspect the action during the configuration phase.
39 * <p/>
40 * This is the perfect time to search for annotations or any other information
41 * required by the action. handlers have the option to cache such inspections
42 * and recall them during {@code before()}, {@code after()} and {@code exception()}.
43 *
44 * @param action the action to be configured
45 * @param method the method that represents the action itself
46 */
47 void configure(@Nonnull Action action, @Nonnull Method method);
48
49 /**
50 * Called before an action is executed.
51 * <p/>
52 * Implementors have the choice of throwing an {@code AbortActionExecution} in
53 * order to signal that the action should not be invoked. In any case this method
54 * returns the arguments to be sent to the action, thus allowing the interceptor
55 * to modify the arguments as it deem necessary. Failure to return an appropriate
56 * value will most likely cause an error during the action's execution.
57 *
58 * @param action the action to execute
59 * @param args the action's arguments
60 *
61 * @return arguments to be sent to the action
62 *
63 * @throws griffon.core.controller.AbortActionExecution if action execution should be aborted.
64 */
65 @Nonnull
66 Object[] before(@Nonnull Action action, @Nonnull Object[] args);
67
68 /**
69 * Called after the action has been aborted or executed, even if an exception
70 * occurred during execution.
71 * <p/>
72 *
73 * @param status a flag that indicates the execution status of the action
74 * @param action the action to execute
75 * @param args the arguments sent to the action
76 * @param result the result of executing the action
77 */
78 @Nullable
79 Object after(@Nonnull ActionExecutionStatus status, @Nonnull Action action, @Nonnull Object[] args, @Nullable Object result);
80
81 /**
82 * Called after the action has been executed when an exception occurred
83 * during execution.
84 * <p/>
85 * The exception will be rethrown by the ActionManager if is not handled by
86 * any interceptor.
87 *
88 * @param exception the exception thrown during the action's execution
89 * @param action the action to execute
90 * @param args the arguments sent to the action during execution
91 *
92 * @return <code>true</code> if the exception was handled successfully,
93 * <code>false</code> otherwise.
94 */
95 boolean exception(@Nonnull Exception exception, @Nonnull Action action, @Nonnull Object[] args);
96 }
|