1 /*
2 * Copyright (C) 2012-2024 RRiBbit.org
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * https://www.apache.org/licenses/LICENSE-2.0
9 *
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 org.rribbit.execution;
17
18 import java.lang.reflect.InvocationTargetException;
19 import java.lang.reflect.Method;
20 import java.util.Collection;
21
22 import org.rribbit.ListenerObject;
23 import org.rribbit.Response;
24
25 /**
26 * This interface specifies a method that can execute a set of {@link ListenerObject}s and return the results.
27 *
28 * @author G.J. Schouten
29 *
30 */
31 public interface ListenerObjectExecutor {
32
33 /**
34 * Executes all {@link ListenerObject}s in the given {@link Collection} and gives the return values back. There is no guarantee on the ordering of the results. This means that
35 * implementations can use any execution order they like.
36 * <p />
37 * The number of {@link ListenerObject} that are executed may be larger than the number of return values that is returned, because some {@link ListenerObject}s may return nothing (void).
38 * <p />
39 * Also note that some {@link ListenerObject}s in the 'listenerObjects' {@link Collection} may not match the parameters in the 'parameters' array. Implementation need to take this into
40 * account and provide proper error handling. When a {@link ListenerObject} does not match the parameter {@link Object}s, it is to be ignored and not to be incorporated into the results.
41 * Generally, the most efficient way of checking this is to just try to call invoke() on the {@link Method} of the {@link ListenerObject}. If any {@link Exception} other than
42 * {@link InvocationTargetException} occurs, it will probably mean that the parameters will not match the {@link Method}. An {@link InvocationTargetException} means that there was a
43 * successful invocation, but a {@link Throwable} was thrown from the method itself.
44 *
45 * @param listenerObjects the {@link ListenerObject}s that have to be executed
46 * @param parameters the parameters to give to the {@link ListenerObject}s
47 * @return the {@link Response} object representing the response of this execution
48 * @throws IllegalArgumentException when 'listenerObjects' is 'null'
49 */
50 <T> Response<T> executeListeners(Collection<ListenerObject> listenerObjects, Object... parameters);
51 }