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;
17
18 import java.util.Collection;
19
20 /**
21 * The bus to which requests can be sent and responses received. The following rules apply to all methods of this interface:
22 *
23 * <ul>
24 * <li>When you send a request, ALL {@link Listener}s that match the request are executed, even if you only send for a single result</li>
25 * <li>The order in which the {@link Listener}s are executed is not specified</li>
26 * <li>The order in which the results are returned is not specified and does not necessarily match the execution order of the {@link Listener}s</li>
27 * <li>If exactly one of the {@link Listener}s throws a {@link Throwable}, then that {@link Throwable} is thrown</li>
28 * <li>If multiple {@link Listener}s throw a {@link Throwable}, then a {@link MultipleThrowablesOccurredException} is thrown, containing all the {@link Throwable}s that were thrown</li>
29 * <li>If any method parameter is 'null', then an {@link IllegalArgumentException} is thrown (null values may occur in the 'parameters' varargs array, however)</li>
30 * </ul>
31 *
32 * @author G.J. Schouten
33 *
34 */
35 public interface RequestResponseBus {
36
37 /**
38 * Send a request to all {@link Listener}s that satisfy the following requirements.
39 * <ul>
40 * <li>They return an {@link Object} that the parameter 'returnType' is assignable from and</li>
41 * <li>they belong to a method with parameters that match the given 'parameters' objects</li>
42 * </ul>
43 *
44 * @param returnType the return type that has to be assignable from the return type of the {@link Listener}s
45 * @param parameters the parameters to give to the {@link Listener}s
46 * @return a single return value from one of the listeners that executed (which one is unspecified) or 'null' if no matching {@link Listener}s were found
47 */
48 <T> T sendForSingleOfClass(Class<T> returnType, Object... parameters);
49
50 /**
51 * Send a request to all {@link Listener}s that satisfy the following requirements.
52 * <ul>
53 * <li>They return an {@link Object} that the parameter 'returnType' is assignable from and</li>
54 * <li>they belong to a method with parameters that match the given 'parameters' objects</li>
55 * </ul>
56 *
57 * The number of {@link Listener}s that are executed may be larger than the number of return values that is returned, because some {@link Listener}s may return nothing (void).
58 *
59 * @param returnType the return type that has to be assignable from the return type of the {@link Listener}s
60 * @param parameters the parameters to give to the {@link Listener}s
61 * @return all return values from the listeners that executed or an empty {@link Collection} if no matching {@link Listener}s were found. This method never returns null.
62 */
63 <T> Collection<T> sendForMultipleOfClass(Class<T> returnType, Object... parameters);
64
65 /**
66 * Send a request to all {@link Listener}s that satisfy the following requirements. Ignore all return values and return nothing.
67 * <ul>
68 * <li>They belong to a method with parameters that match the given 'parameters' objects</li>
69 * </ul>
70 *
71 * @param parameters the parameters to give to the {@link Listener}s
72 */
73 void sendForNothing(Object... parameters);
74
75 /**
76 * Send a request to all {@link Listener}s that satisfy the following requirements.
77 * <ul>
78 * <li>They have a hint that is equals to the 'hint' parameter and</li>
79 * <li>they belong to a method with parameters that match the given 'parameters' objects</li>
80 * </ul>
81 *
82 * @param hint the hint that has to be equal to the hint of the {@link Listener}s
83 * @param parameters the parameters to give to the {@link Listener}s
84 * @return a single return value from one of the listeners that executed (which one is unspecified) or 'null' if no matching {@link Listener}s were found
85 * or none of them returned anything
86 */
87 <T> T sendForSingleWithHint(String hint, Object... parameters);
88
89 /**
90 * Send a request to all {@link Listener}s that satisfy the following requirements.
91 * <ul>
92 * <li>They have a hint that is equals to the 'hint' parameter and</li>
93 * <li>they belong to a method with parameters that match the given 'parameters' objects</li>
94 * </ul>
95 *
96 * The number of {@link Listener}s that are executed may be larger than the number of return values that is returned, because some {@link Listener}s may return nothing (void).
97 *
98 * @param hint the hint that has to be equal to the hint of the {@link Listener}s
99 * @param parameters the parameters to give to the {@link Listener}s
100 * @return all return values from the listeners that executed or an empty {@link Collection} if no matching {@link Listener}s were found or none of them returned anything.
101 * This method never returns null.
102 */
103 <T> Collection<T> sendForMultipleWithHint(String hint, Object... parameters);
104
105 /**
106 * Send a request to all {@link Listener}s that satisfy the following requirements. Ignore all return values and return nothing.
107 * <ul>
108 * <li>They have a hint that is equals to the 'hint' parameter and</li>
109 * <li>they belong to a method with parameters that match the given 'parameters' objects</li>
110 * </ul>
111 *
112 * @param hint the hint that has to be equal to the hint of the {@link Listener}s
113 * @param parameters the parameters to give to the {@link Listener}s
114 */
115 void sendForNothingWithHint(String hint, Object... parameters);
116
117 /**
118 * Send a request to all {@link Listener}s that satisfy the following requirements.
119 * <ul>
120 * <li>They return an {@link Object} that the parameter 'returnType' is assignable from and</li>
121 * <li>they have a hint that is equals to the 'hint' parameter and</li>
122 * <li>they belong to a method with parameters that match the given 'parameters' objects</li>
123 * </ul>
124 *
125 * @param returnType the return type that has to be assignable from the return type of the {@link Listener}s
126 * @param hint the hint that has to be equal to the hint of the {@link Listener}s
127 * @param parameters the parameters to give to the {@link Listener}s
128 * @return a single return value from one of the listeners that executed (which one is unspecified) or 'null' if no matching {@link Listener}s were found
129 */
130 <T> T sendForSingleOfClassWithHint(Class<T> returnType, String hint, Object... parameters);
131
132 /**
133 * Send a request to all {@link Listener}s that satisfy the following requirements.
134 * <ul>
135 * <li>They return an {@link Object} that the parameter 'returnType' is assignable from and</li>
136 * <li>they have a hint that is equals to the 'hint' parameter and</li>
137 * <li>they belong to a method with parameters that match the given 'parameters' objects</li>
138 * </ul>
139 *
140 * The number of {@link Listener}s that are executed may be larger than the number of return values that is returned, because some {@link Listener}s may return nothing (void).
141 *
142 * @param returnType the return type that has to be assignable from the return type of the {@link Listener}s
143 * @param hint the hint that has to be equal to the hint of the {@link Listener}s
144 * @param parameters the parameters to give to the {@link Listener}s
145 * @return all return values from the listeners that executed or an empty {@link Collection} if no matching {@link Listener}s were found. This method never returns null.
146 */
147 <T> Collection<T> sendForMultipleOfClassWithHint(Class<T> returnType, String hint, Object... parameters);
148
149 /**
150 * Equivalent to {@link #sendForSingleWithHint(String, Object...)}, since that is probably the most widely used method, because generally, when you know the hint, you know
151 * the returntype and you don't have to pass it specifically.
152 * <p />
153 * This method is just a convenience shorthand method with a shorter name.
154 *
155 * @param hint
156 * @param parameters
157 * @return same as sendForSingleWithHint
158 */
159 <T> T send(String hint, Object... parameters);
160 }