1 package org.apache.helix;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.util.List;
23
24 import org.apache.helix.controller.GenericHelixController;
25 import org.apache.helix.healthcheck.ParticipantHealthReportCollector;
26 import org.apache.helix.model.HelixConfigScope.ConfigScopeProperty;
27 import org.apache.helix.participant.HelixStateMachineEngine;
28 import org.apache.helix.participant.StateMachineEngine;
29 import org.apache.helix.spectator.RoutingTableProvider;
30 import org.apache.helix.store.zk.ZkHelixPropertyStore;
31
32
33 /**
34 * Class that represents the Helix Agent.
35 * First class Object any process will interact with<br/>
36 * General flow <blockquote>
37 *
38 * <pre>
39 * manager = HelixManagerFactory.getManagerFor<ROLE>(); ROLE can be participant, spectator or a controller<br/>
40 * manager.connect();
41 * manager.addSOMEListener();
42 * manager.start()
43 * After start is invoked the subsequent interactions will be via listener onChange callbacks
44 * There will be 3 scenarios for onChange callback, which can be determined using NotificationContext.type
45 * INIT -> will be invoked the first time the listener is added
46 * CALLBACK -> will be invoked due to datachange in the property value
47 * FINALIZE -> will be invoked when listener is removed or session expires
48 * manager.disconnect()
49 * </pre>
50 *
51 * </blockquote> Default implementations available
52 *
53 * @see HelixStateMachineEngine for participant
54 * @see RoutingTableProvider for spectator
55 * @see GenericHelixController for controller
56 */
57 public interface HelixManager
58 {
59
60 public static final String ALLOW_PARTICIPANT_AUTO_JOIN = "ALLOW_PARTICIPANT_AUTO_JOIN";
61
62 /**
63 * Start participating in the cluster operations. All listeners will be
64 * initialized and will be notified for every cluster state change This method
65 * is not re-entrant. One cannot call this method twice.
66 *
67 * @throws Exception
68 */
69 void connect() throws Exception;
70
71 /**
72 * Check if the connection is alive, code depending on cluster manager must
73 * always do this if( manager.isConnected()){ //custom code } This will
74 * prevent client in doing anything when its disconnected from the cluster.
75 * There is no need to invoke connect again if isConnected return false.
76 *
77 * @return
78 */
79 boolean isConnected();
80
81 /**
82 * Disconnect from the cluster. All the listeners will be removed and
83 * disconnected from the server. Its important for the client to ensure that
84 * new manager instance is used when it wants to connect again.
85 */
86 void disconnect();
87
88 /**
89 * @see IdealStateChangeListener#onIdealStateChange(List, NotificationContext)
90 * @param listener
91 * @throws Exception
92 */
93 void addIdealStateChangeListener(IdealStateChangeListener listener)
94 throws Exception;
95
96 /**
97 * @see LiveInstanceChangeListener#onLiveInstanceChange(List,
98 * NotificationContext)
99 * @param listener
100 */
101 void addLiveInstanceChangeListener(LiveInstanceChangeListener listener)
102 throws Exception;
103
104 /**
105 * @see ConfigChangeListener#onConfigChange(List, NotificationContext)
106 * @param listener
107 *
108 * @deprecated replaced by addInstanceConfigChangeListener()
109 */
110 void addConfigChangeListener(ConfigChangeListener listener) throws Exception;
111
112 /**
113 * @see InstanceConfigChangeListener#onInstanceConfigChange(List, NotificationContext)
114 * @param listener
115 *
116 */
117 void addInstanceConfigChangeListener(InstanceConfigChangeListener listener) throws Exception;
118
119 /**
120 * @see ScopedConfigChangeListener#onConfigChange(List, NotificationContext)
121 * @param listener
122 * @param scope
123 */
124 void addConfigChangeListener(ScopedConfigChangeListener listener, ConfigScopeProperty scope) throws Exception;
125
126 /**
127 * @see MessageListener#onMessage(String, List, NotificationContext)
128 * @param listener
129 * @param instanceName
130 */
131 void addMessageListener(MessageListener listener, String instanceName)
132 throws Exception;
133
134 /**
135 * @see CurrentStateChangeListener#onStateChange(String, List,
136 * NotificationContext)
137 * @param listener
138 * @param instanceName
139 */
140
141 void addCurrentStateChangeListener(CurrentStateChangeListener listener,
142 String instanceName, String sessionId) throws Exception;
143
144 /**
145 * @see HealthStateChangeListener#onHealthChange(String, List,
146 * NotificationContext)
147 * @param listener
148 * @param instanceName
149 */
150 void addHealthStateChangeListener(HealthStateChangeListener listener,
151 String instanceName) throws Exception;
152
153 /**
154 * @see ExternalViewChangeListener#onExternalViewChange(List,
155 * NotificationContext)
156 * @param listener
157 */
158 void addExternalViewChangeListener(ExternalViewChangeListener listener)
159 throws Exception;
160
161 /**
162 * Add listener for controller change
163 *
164 * Used in distributed cluster controller
165 */
166 void addControllerListener(ControllerChangeListener listener);
167
168 /**
169 * Removes the listener. If the same listener was used for multiple changes,
170 * all change notifications will be removed.<br/>
171 * This will invoke onChange method on the listener with
172 * NotificationContext.type set to FINALIZE. Listener can clean up its state.<br/>
173 * The data provided in this callback may not be reliable.<br/>
174 * When a session expires all listeners will be removed and re-added
175 * automatically. <br/>
176 * This provides the ability for listeners to either reset their state or do
177 * any cleanup tasks.<br/>
178 *
179 * @param listener
180 * @return
181 */
182 boolean removeListener(PropertyKey key, Object listener);
183 /**
184 * Return the client to perform read/write operations on the cluster data
185 * store
186 *
187 * @return ClusterDataAccessor
188 */
189 HelixDataAccessor getHelixDataAccessor();
190
191 /**
192 * Get config accessor
193 *
194 * @return
195 */
196 ConfigAccessor getConfigAccessor();
197
198 /**
199 * Returns the cluster name associated with this cluster manager
200 *
201 * @return
202 */
203 String getClusterName();
204
205 /**
206 * Returns the instanceName used to connect to the cluster
207 *
208 * @return
209 */
210
211 String getInstanceName();
212
213 /**
214 * Get the sessionId associated with the connection to cluster data store.
215 */
216 String getSessionId();
217
218 /**
219 * The time stamp is always updated when a notification is received. This can
220 * be used to check if there was any new notification when previous
221 * notification was being processed. This is updated based on the
222 * notifications from listeners registered.
223 */
224 long getLastNotificationTime();
225
226 /**
227 * Provides admin interface to setup and modify cluster.
228 *
229 * @return
230 */
231 HelixAdmin getClusterManagmentTool();
232
233 /**
234 * Get property store
235 *
236 * @return
237 */
238 ZkHelixPropertyStore<ZNRecord> getHelixPropertyStore();
239
240 /**
241 * Messaging service which can be used to send cluster wide messages.
242 *
243 */
244 ClusterMessagingService getMessagingService();
245
246 /**
247 * Participant only component that periodically update participant health
248 * report to cluster manager server.
249 *
250 */
251 ParticipantHealthReportCollector getHealthReportCollector();
252
253 /**
254 * Get cluster manager instance type
255 *
256 * @return
257 */
258 InstanceType getInstanceType();
259
260 /**
261 * Get cluster manager version
262 *
263 * @return the cluster manager version
264 */
265 String getVersion();
266
267 /**
268 * Get helix manager properties read from
269 * helix-core/src/main/resources/cluster-manager.properties
270 *
271 * @return
272 */
273 HelixManagerProperties getProperties();
274
275 /**
276 *
277 * @return the state machine engine
278 */
279 StateMachineEngine getStateMachineEngine();
280
281 /**
282 * Check if the cluster manager is the leader
283 *
284 * @return true if this is a controller and a leader of the cluster
285 */
286 boolean isLeader();
287
288 /**
289 * start timer tasks when becomes leader
290 *
291 */
292 void startTimerTasks();
293
294 /**
295 * stop timer tasks when becomes standby
296 *
297 */
298 void stopTimerTasks();
299
300 /**
301 * Add a callback that is invoked before a participant joins the cluster.</br>
302 * This zookeeper connection is established at this time and one can read existing cluster data</br>
303 * The purpose of this method is to allow application to have additional logic to validate their existing state and check for any errors.
304 * If the validation fails, throw exception/disable the instance. s
305 * @see PreConnectCallback#onPreConnect()
306 * @param callback
307 */
308 void addPreConnectCallback(PreConnectCallback callback);
309
310 /**
311 * Add a LiveInstanceInfoProvider that is invoked before creating liveInstance.</br>
312 * This allows applications to provide additional metadata that will be published to zk and made available for discovery</br>
313 *
314 * @see LiveInstanceInfoProvider#getAdditionalLiveInstanceInfo()
315 * @param liveInstanceInfoProvider
316 */
317 void setLiveInstanceInfoProvider(LiveInstanceInfoProvider liveInstanceInfoProvider);
318 }