ActionHandler.java
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 }