1 /*
2 Copyright 2007 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.distribution;
17
18 import fulmine.IDomain;
19 import fulmine.ILifeCycle;
20 import fulmine.IType;
21 import fulmine.context.IFrameworkContext;
22 import fulmine.context.IRemoteUpdateHandler;
23 import fulmine.distribution.channel.IChannel;
24 import fulmine.event.listener.IEventListener;
25 import fulmine.event.subscription.ISubscription;
26 import fulmine.event.subscription.ISubscriptionListener;
27 import fulmine.model.container.IContainer;
28 import fulmine.protocol.specification.IFrameReader;
29 import fulmine.protocol.specification.IFrameWriter;
30 import fulmine.rpc.IRpcTransmissionManager;
31
32 /**
33 * Manages subscriptions for distribution of events within the local context and
34 * from remote contexts. Application code uses the subscribe method to receive
35 * distribution of events from both local and remote {@link IContainer}
36 * instances.
37 *
38 * @see IFrameworkContext
39 * @author Ramon Servadei
40 */
41 public interface IDistributionManager extends ILifeCycle,
42 IRetransmissionManager, IRpcTransmissionManager
43 {
44
45 /**
46 * Subscribe the listener for the events generated by the {@link IContainer}
47 * instance(s) in the identified context that match the type, domain and
48 * identity regular expression. The supplied listener will be registered
49 * against the matching container instance(s). Events (changes to the
50 * container instance(s)) will be received by the listener.
51 * <p>
52 * The container type and domain is matched exactly. However, a 'wildcard'
53 * match for the type or domain can be specified using
54 * {@link ISubscription#WILDCARD_TYPE} and
55 * {@link ISubscription#WILDCARD_DOMAIN}. The identity regular expression
56 * can identify an exact container identity or it can identify multiple
57 * container identities (it is a regular expression matched against
58 * container identities).
59 * <p>
60 * All subscription operations occur indefinitely; the operation examines
61 * all current containers and then future created containers for an identity
62 * match. The listener is registered against any matching container. The
63 * subscription exists until either the context terminates or the
64 * {@link #unsubscribe(String, String, IType, IDomain, IEventListener)}
65 * method is invoked with the same arguments. Using a regular expression
66 * matching subscription allows a listener to receive updates for containers
67 * whose identities are currently unknown or do not yet exist.
68 * <p>
69 * When the subscription is for a remote context (the contextIdentity does
70 * not match the local context identity), the subscription request is
71 * transmitted to the named remote context. The remote context handles the
72 * subscription using the same contract as for a local subscription. If the
73 * remote context has not yet come online, the subscription is saved until
74 * the identified remote context becomes available, at which point the
75 * subscription is transmitted.
76 * <p>
77 * Calling this method multiple times with the same arguments has no effect;
78 * it is idempotent.
79 *
80 * @param contextIdentity
81 * the identity of context where the container(s) exist
82 * @param identityRegularExpression
83 * the identity regular expression that will be matched against a
84 * container's identity
85 * @param type
86 * the type of the container
87 * @param domain
88 * the domain of the container
89 * @param listener
90 * the listener that will be registered for receiving events from
91 * the matching container(s)
92 * @return <code>true</code> if the subscription was created,
93 * <code>false</code> if it already existed
94 * @see #unsubscribe(String, String, IType, IDomain, IEventListener)
95 */
96 boolean subscribe(String contextIdentity, String identityRegularExpression,
97 IType type, IDomain domain, IEventListener listener);
98
99 /**
100 * Unsubscribe the listener from the {@link IContainer} instance(s)
101 * identified by the type, domain and identity regular expression in the
102 * specified context.
103 * <p>
104 * The {@link #subscribe(String, String, IType, IDomain, IEventListener)}
105 * method is <b>idempotent</b> so if it is called multiple times with the
106 * same arguments, <b>one</b> call to
107 * {@link #unsubscribe(String, String, IType, IDomain, IEventListener)} will
108 * remove it.
109 * <p>
110 * Two subscriptions with equal type and domain but identity "foo.*" and
111 * "foo" are separate subscriptions and require two unsubscribe operations;
112 * the unsubscribe for "foo.*" does not unsubscribe the "foo" subscription.
113 *
114 * @param contextIdentity
115 * the identity of the remote context
116 * @param identityRegularExpression
117 * the identity regular expression that will be matched against a
118 * container's identity
119 * @param type
120 * the type of the container
121 * @param domain
122 * the domain of the container
123 * @param listener
124 * the listener that will be unregistered from receiving events
125 * from matching container(s)
126 * @return <code>true</code> if the subscription was found and removed,
127 * <code>false</code> otherwise
128 * @see #subscribe(String, String, IType, IDomain, IEventListener)
129 */
130 boolean unsubscribe(String contextIdentity,
131 String identityRegularExpression, IType type, IDomain domain,
132 IEventListener listener);
133
134 /**
135 * Add a container subscription listener. This will be activated when
136 * container subscription and unsubscription occurs. The listener can react
137 * to the subscription requests and perform any necessary work to create
138 * and/or maintain the targeted containers for the subscription. This is
139 * complimentary to the actual subscribe function.
140 * <p>
141 * The listener will be added to a list only if it does not already exist in
142 * the list. Subscription events will be notified to all listeners in the
143 * list in the order they are added.
144 *
145 * @param listener
146 * a listener to add to an internal list.
147 * @return <code>true</code> if the listener was added, <code>false</code>
148 * otherwise
149 */
150 boolean addSubscriptionListener(ISubscriptionListener listener);
151
152 /**
153 * Remove a container subscription listener. The listener will no longer
154 * receive events when a container subscription/unsubscription occurs.
155 *
156 * @param listener
157 * the listener to remove
158 * @return <code>true</code> if the listener was found and removed,
159 * <code>false</code> otherwise
160 */
161 boolean removeSubscriptionListener(ISubscriptionListener listener);
162
163 /**
164 * Get the frame writer for this context
165 *
166 * @return the {@link IFrameWriter} for this context
167 */
168 IFrameWriter getFrameWriter();
169
170 /**
171 * Get the frame reader for this context
172 *
173 * @return the {@link IFrameReader} for this context
174 */
175 IFrameReader getFrameReader();
176
177 /**
178 * Get all the currently connected channels
179 *
180 * @return an array of the currently connected {@link IChannel} instances
181 */
182 IChannel[] getConnectedChannels();
183
184 /**
185 * Update a named field with a new value in a container in a remote context.
186 * This operation passes through the permission profile of this context. The
187 * operation may not succeed in the remote context (possibly due to
188 * permission rights not being sufficient for the operation).
189 * <p>
190 * <b>Note: This operation may be synchronous and may therefore block on
191 * I/O.</b>
192 *
193 * @see #setRemoteUpdateHandler(IRemoteUpdateHandler)
194 *
195 * @param remoteContextIdentity
196 * the identity of the remote context where the container is
197 * hosted
198 * @param identity
199 * the identity of the container with the field to change
200 * @param type
201 * the type of the container
202 * @param domain
203 * the domain of the container
204 * @param fieldName
205 * the field name in the container to update
206 * @param fieldValueAsString
207 * the field value (as a string) to set as the new value for the
208 * named field
209 * @return a string encapsulating the result of the operation.
210 */
211 String updateRemoteContainer(String remoteContextIdentity, String identity,
212 IType type, IDomain domain, String fieldName, String fieldValueAsString);
213 }