1 /*
2 Copyright 2008 Ramon Servadei
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 http://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 fulmine.event.subscription;
17
18 import java.util.Collection;
19 import java.util.Collections;
20 import java.util.List;
21
22 import fulmine.IAddressable;
23 import fulmine.ILifeCycle;
24 import fulmine.event.IEvent;
25 import fulmine.event.IEventSource;
26 import fulmine.event.listener.IEventListener;
27
28 /**
29 * Manages subscriptions for the {@link IEvent} events generated by
30 * {@link IEventSource} instances. The subscriptions are encapsulated in
31 * {@link ISubscription} instances. Subscription requests are issued to the
32 * manager using an {@link ISubscriptionParameters} object that defines what
33 * event sources to subscribe for. This is also the key used to store the
34 * {@link ISubscription} instance.
35 * <p>
36 * Once a subscription instance is created, any number of listeners (
37 * {@link IEventListener} instances) can be associated with it via the
38 * {@link #addListener(ISubscriptionParameters, IEventListener)} method. When a
39 * listener is added to the subscription, the subscription will register the
40 * listener with any currently subscribed event sources.
41 * <p>
42 * Subscription match processing occurs when the subscription is issued and
43 * continues until the subscription is cancelled. This allows subscriptions for
44 * event sources not yet created to be issued. When the event source is created,
45 * the utility method {@link #eventSourceCreated(IAddressable)} should be called
46 * and the subscriptions registered with the manager are checked for a match
47 * against the created source.
48 *
49 * @author Ramon Servadei
50 */
51 public interface ISubscriptionManager extends ILifeCycle
52 {
53 /**
54 * Create an {@link ISubscription} for the event source(s) represented in
55 * the subscription parameters. The created subscription is keyed against
56 * the parameters argument.
57 * <p>
58 * This is an idempotent operation.
59 *
60 * @param parameters
61 * the subscription parameters identifying the subscription
62 * @return <code>true</code> if the subscription was created,
63 * <code>false</code> if it already existed
64 * @see #getSubscribedSources(ISubscriptionParameters)
65 * @see #unsubscribe(ISubscriptionParameters)
66 */
67 boolean subscribe(ISubscriptionParameters parameters);
68
69 /**
70 * Remove the subscription represented by the parameters. The subscription
71 * is found by looking it up against the parameters as its key.
72 * <p>
73 * This unregisters the listener(s) associated with the subscription from
74 * the event source(s) that the subscription matched and destroys the
75 * associated {@link ISubscription} instance.
76 * <p>
77 * This is an idempotent operation.
78 *
79 * @param parameters
80 * the subscription parameters identifying the subscription
81 * @return <code>true</code> if a subscription was found, <code>false</code>
82 * otherwise
83 * @see #getSubscribedSources(ISubscriptionParameters)
84 * @see #subscribe(ISubscriptionParameters)
85 */
86 boolean unsubscribe(ISubscriptionParameters parameters);
87
88 /**
89 * Add the listener to the {@link IEventListener} instances associated with
90 * the {@link ISubscription} represented by the parameters. The subscription
91 * is found using the same lookup semantics as
92 * {@link #getSubscription(ISubscriptionParameters)}.
93 * <p>
94 * On adding, the subscription will register the listener with any currently
95 * matched {@link IEventSource} instances.
96 * <p>
97 * This is an idempotent operation.
98 *
99 *
100 * @param parameters
101 * the subscription parameters identifying the subscription
102 * @param listener
103 * the listener to add to the subscription's list of listeners
104 * @return <code>true</code> if the listener was added, <code>false</code>
105 * if it already existed
106 */
107 boolean addListener(ISubscriptionParameters parameters,
108 IEventListener listener);
109
110 /**
111 * Remove the listener from the {@link IEventListener} instances associated
112 * with the {@link ISubscription} represented by the parameters. The
113 * subscription is found using the same lookup semantics as
114 * {@link #getSubscription(ISubscriptionParameters)}.
115 * <p>
116 * On removal, the subscription will unregister the listener from any
117 * currently matched {@link IEventSource} instances.
118 * <p>
119 * This is an idempotent operation.
120 *
121 * @param parameters
122 * the subscription parameters identifying the subscription
123 * @param listener
124 * the listener to remove from the subscription's list of
125 * listeners
126 * @return <code>true</code> if the listener was removed, <code>false</code>
127 * if it was not found
128 */
129 boolean removeListener(ISubscriptionParameters parameters,
130 IEventListener listener);
131
132 /**
133 * Get a <u>copy</u> of the {@link Collection} of all the event sources that
134 * are currently subscribed for.
135 *
136 * @return a copy of the {@link Collection} of all the event source
137 * instances that are currently subscribed for
138 */
139 Collection<IEventSource> getSubscribedSources();
140
141 /**
142 * Get a <u>copy</u> of the {@link Collection} of the currently subscribed
143 * event sources that are matched by the subscription parameters.
144 * <p>
145 * This does a matching operation to find any other {@link ISubscription}s
146 * that would {@link ISubscriptionParameters#includes(IAddressable) include}
147 * these parameters and then adds the {@link IEventSource}s to the
148 * collection to return.
149 * <p>
150 * This is not a key lookup operation.
151 *
152 * @param parameters
153 * the subscription parameters to match against event sources
154 * currently subscribed for
155 * @return a copy of the {@link Collection} of the event sources currently
156 * subscribed for and that are matched by the subscription
157 * parameters argument
158 */
159 Collection<IEventSource> getSubscribedSources(
160 ISubscriptionParameters parameters);
161
162 /**
163 * Determine if there is at least one {@link ISubscription} that has a match
164 * reference for the event source.
165 * <p>
166 * This checks if the event source is already subscribed. To find out if
167 * this source would be subscribed, use
168 * {@link #includes(ISubscriptionParameters)}.
169 *
170 * @param source
171 * the event source to check for at least one subscription within
172 * this manager
173 * @return <code>true</code> if the source is found in at least one
174 * subscription within this manager
175 */
176 boolean isSubscribed(IEventSource source);
177
178 /**
179 * Determine if there is at least one {@link ISubscription} instance whose
180 * subscription parameters <b>include</b> the parameters passed in.
181 * <p>
182 * This operation is <b>not</b> a key lookup and will search through all
183 * subscriptions until one is found that would include the parameters.
184 *
185 * @see ISubscriptionParameters#includes(IAddressable)
186 * @param parameters
187 * the parameters to check
188 * @return <code>true</code> if there is at least one subscription instance
189 * that includes the parameters
190 */
191 boolean includes(IAddressable parameters);
192
193 /**
194 * Method to invoke when a new {@link IEventSource} is created. This
195 * provides the manager with the mechanism to be notified when event sources
196 * are created and go through existing subscriptions to identify if the new
197 * event source should be subscribed for.
198 *
199 * @param identity
200 * identifies the attributes of the created event source
201 */
202 void eventSourceCreated(IAddressable identity);
203
204 /**
205 * Method to invoke when an {@link IEventSource} is destroyed. Complimentary
206 * to {@link #eventSourceCreated(IAddressable)}.
207 *
208 * @param identity
209 * identifies the attributes of the destroyed event source
210 */
211 void eventSourceDestroyed(IAddressable identity);
212
213 /**
214 * Get a <b>copy</b> of the {@link IEventListener} instances that have been
215 * added to the subscription identified by the parameters. The subscription
216 * is found using a key lookup operation; the subscription is found by
217 * association with the parameters.
218 * <p>
219 * This operation performs no semantic matching with wildcards, it is a key
220 * lookup operation.
221 *
222 * @param parameters
223 * the subscription parameters identifying the subscription
224 * @return the list of {@link IEventListener} instances for the identified
225 * subscription or {@link Collections#emptyList()}
226 */
227 List<IEventListener> getListeners(ISubscriptionParameters parameters);
228 }