View Javadoc
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.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  }