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.connection;
17
18 import fulmine.ILifeCycle;
19 import fulmine.context.IFrameworkContext;
20 import fulmine.distribution.IHeartbeatMonitor;
21 import fulmine.distribution.events.ContextDiscoveredEvent;
22 import fulmine.distribution.events.ContextNotAvailableEvent;
23
24 /**
25 * Discovers other remote {@link IFrameworkContext} instances that have
26 * connected to the communication network. When a new remote context is
27 * discovered, this raises a {@link ContextDiscoveredEvent} event.
28 * <p>
29 * All discoverer instances periodically send out a 'pulse' onto the network.
30 * This period is determined from
31 * {@link IHeartbeatMonitor#getNetworkHeartbeatPeriod()}. This pulse is the
32 * mechanism for initial discovery and continual verification that a remote
33 * context is still available. When a discoverer misses a set number of pulses
34 * from a remote context, it raises a {@link ContextNotAvailableEvent}.
35 *
36 * @see IHeartbeatMonitor#getAllowableNetworkHeartbeatMissCount()
37 * @author Ramon Servadei
38 */
39 public interface IConnectionDiscoverer extends ILifeCycle, IHeartbeatMonitor
40 {
41 /**
42 * Start discovering other remote {@link IFrameworkContext} instances
43 */
44 void start();
45
46 /**
47 * Send out a pulse on the discovery network. This allows other
48 * {@link IConnectionDiscoverer} instances on the same network to detect
49 * this one.
50 */
51 void pulse();
52
53 /**
54 * Disable the discoverer from sending out pulses. The discoverer will still
55 * detect other {@link IConnectionDiscoverer} instances from their pulses,
56 * it just will not send out any pulses for itself; effectively it is in
57 * listening-only mode.
58 */
59 void disablePulsing();
60
61 /**
62 * Enable the discoverer to send out pulses. By default, calling
63 * {@link #start()} sets the discoverer in this mode <b>unless</b>
64 * {@link #disablePulsing()} is called before {@link #start()}.
65 */
66 void enablePulsing();
67
68 /**
69 * Informs the discoverer that a connection to the named remote context has
70 * been destroyed. The discoverer should remove any information regarding
71 * this context and be prepared to re-discover it.
72 *
73 * @param remoteContextIdentity
74 * the remote context that has had a connection destroyed
75 */
76 void connectionDestroyed(String remoteContextIdentity);
77 }