1 /*
2 * Copyright (C) 2012-2025 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.retrieval;
17
18 import java.util.Collection;
19
20 import org.rribbit.ListenerObject;
21 import org.rribbit.creation.ListenerObjectCreator;
22
23 /**
24 * A {@link ListenerObjectRetriever} retrieves the {@link ListenerObject}s that were created by one or more {@link ListenerObjectCreator}s.
25 *
26 * @author G.J. Schouten
27 *
28 */
29 public interface ListenerObjectRetriever {
30
31 /**
32 * Returns a {@link Collection} of all {@link ListenerObject}s that are known to this {@link ListenerObjectRetriever}.
33 *
34 * @return a {@link Collection} of all known {@link ListenerObject}s, or an empty {@link Collection} if there are none. This method never returns null.
35 */
36 Collection<ListenerObject> getListenerObjects();
37
38 /**
39 * Returns a {@link Collection} of {@link ListenerObject}s that satisfy the following requirements.
40 * <ul>
41 * <li>The parameter 'returnType' is assignable from the returntype of the {@link ListenerObject}</li>
42 * </ul>
43 *
44 * @param returnType the return type that has to be assignable from the returntype of each {@link ListenerObject}
45 * @return a {@link Collection} of {@link ListenerObject}s that satisfy the above requirements, or an empty {@link Collection} if there were no matches. This method never returns null.
46 * @throws IllegalArgumentException when 'returnType' is 'null'
47 */
48 Collection<ListenerObject> getListenerObjects(Class<?> returnType);
49
50 /**
51 * Returns a {@link Collection} of {@link ListenerObject}s that satisfy the following requirements.
52 * <ul>
53 * <li>The hints of the {@link ListenerObject} must contain the 'hint' parameter</li>
54 * </ul>
55 *
56 * @param hint the hint that has to be contained by the hints of each {@link ListenerObject}
57 * @return a {@link Collection} of {@link ListenerObject}s that satisfy the above requirements, or an empty {@link Collection} if there were no matches. This method never returns null.
58 * @throws IllegalArgumentException when 'hint' is 'null'
59 */
60 Collection<ListenerObject> getListenerObjects(String hint);
61
62 /**
63 * Returns a {@link Collection} of {@link ListenerObject}s that satisfy the following requirements.
64 * <ul>
65 * <li>The parameter 'returnType' is assignable from the returntype of the {@link ListenerObject}</li>
66 * <li>The hints of the {@link ListenerObject} must contain the 'hint' parameter</li>
67 * </ul>
68 *
69 * @param returnType the return type that has to be assignable from the returntype of each {@link ListenerObject}
70 * @param hint the hint that has to be contained by the hints of each {@link ListenerObject}
71 * @return a {@link Collection} of {@link ListenerObject}s that satisfy the above requirements, or an empty {@link Collection} if there were no matches. This method never returns null.
72 * @throws IllegalArgumentException when 'returnType' or 'hint' is 'null'
73 */
74 Collection<ListenerObject> getListenerObjects(Class<?> returnType, String hint);
75 }