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