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.List;
20
21 import fulmine.Domain;
22 import fulmine.IDestroyable;
23 import fulmine.IDomain;
24 import fulmine.IType;
25 import fulmine.Type;
26 import fulmine.event.IEventSource;
27 import fulmine.event.listener.IEventListener;
28
29 /**
30 * Encapsulates a single subscription for {@link IEventSource} instances. The
31 * subscription has a collection of {@link IEventListener} instances that are
32 * registered as listeners against all event sources that are matched by the
33 * subscription. The subscription also stores references to all matching event
34 * sources.
35 * <p>
36 * A subscription operates with an {@link ISubscriptionManager}. The manager
37 * uses the subscription to determine if it would match an event source and, if
38 * it does, the manager adds the event source as a match reference. On adding,
39 * the subscription registers its listeners against the event source.
40 * <p>
41 * Subscriptions are defined by an {@link ISubscriptionParameters} instance that
42 * identifies that type, domain and identity attributes of matching event
43 * sources. A subscription can match the attributes exactly or use wildcards.
44 * The wildcard match for the type or domain can be specified using
45 * {@link ISubscription#WILDCARD_TYPE} and {@link ISubscription#WILDCARD_DOMAIN}
46 * . The identity specified for a subscription is a regular expression matching
47 * one or more event source identities.
48 *
49 * @author Ramon Servadei
50 */
51 public interface ISubscription extends IDestroyable, ISubscriptionParameters
52 {
53
54 /**
55 * Wildcard for identity subscriptions; this allows any identity to be
56 * matched by a subscription.
57 */
58 String WILDCARD_ID_REGEX = ".*";
59
60 /**
61 * Wildcard for type subscriptions; this allows any type to be matched by a
62 * subscription.
63 */
64 IType WILDCARD_TYPE = Type.get(-2);
65
66 /**
67 * Wildcard for domain subscriptions; this allows any domain to be matched
68 * by a subscription.
69 */
70 IDomain WILDCARD_DOMAIN = Domain.get(-2);
71
72 /**
73 * Add the event source as a matched reference.
74 * <p>
75 * The source is only added if the subscription does not already contain the
76 * source as a match.
77 * <p>
78 * This is an <u>idempotent</u> operation.
79 *
80 * @param source
81 * the event source
82 * @return <code>true</code> if the event source was added,
83 * <code>false</code> if the subscription already has the source as
84 * a matched reference
85 */
86 boolean addMatch(IEventSource source);
87
88 /**
89 * Remove the event source(s) identified by the parameters from this
90 * subscription's matched references.
91 * <p>
92 * <b>Note:</b> if the parameters include wildcards, multiple event sources
93 * may be removed.
94 *
95 * @param parameters
96 * the subscription parameters identifying any matching event
97 * sources to remove
98 *
99 * @return <code>true</code> if at least one event source was found and
100 * removed, <code>false</code> if no event source was found to
101 * remove
102 */
103 boolean removeMatch(ISubscriptionParameters parameters);
104
105 /**
106 * Get a <b>copy</b> of the internal {@link Collection} of all the
107 * {@link IEventSource} instances referenced by this subscription. The order
108 * of the collection elements is arbitrary.
109 *
110 * @return a <b>copy</b> of the collection of all {@link IEventSource}
111 * instances referenced by this subscription
112 */
113 Collection<IEventSource> getMatches();
114
115 /**
116 * Get a <b>copy</b> of the internal {@link List} of all the
117 * {@link IEventListener} instances used by the subscription to register
118 * against the subscribed {@link IEventSource} instances.
119 *
120 * @return a <b>copy</b> of the internal {@link List} of all the listeners
121 * that are registered against all subscribed {@link IEventSource}
122 * instances. The order of the listeners is the order of calling
123 * {@link #addListener(IEventListener)}.
124 */
125 List<IEventListener> getListeners();
126
127 /**
128 * Remove the listener from the {@link IEventListener} instances associated
129 * with this {@link ISubscription}. The subscription will remove the
130 * listener from any currently matched {@link IEventSource} instances.
131 * <p>
132 * This is an idempotent operation.
133 *
134 *
135 * @param listener
136 * the listener to remove from the subscription's list of
137 * listeners
138 * @return <code>true</code> if the listener was removed, <code>false</code>
139 * if it was not found
140 */
141 boolean removeListener(IEventListener listener);
142
143 /**
144 * Add the listener to the {@link IEventListener} instances associated with
145 * this {@link ISubscription}. The subscription will register the listener
146 * with any currently matched {@link IEventSource} instances.
147 * <p>
148 * This is an idempotent operation.
149 *
150 *
151 * @param listener
152 * the listener to add to the subscription's list of listeners
153 * @return <code>true</code> if the listener was added, <code>false</code>
154 * if it already existed
155 */
156 boolean addListener(IEventListener listener);
157 }