1 /**
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 */
19 package org.apache.hadoop.hbase.master;
20
21 import java.util.List;
22 import java.util.Map;
23
24 import edu.umd.cs.findbugs.annotations.Nullable;
25 import org.apache.hadoop.hbase.classification.InterfaceAudience;
26 import org.apache.hadoop.hbase.conf.ConfigurationObserver;
27 import org.apache.hadoop.conf.Configurable;
28 import org.apache.hadoop.conf.Configuration;
29 import org.apache.hadoop.hbase.ClusterStatus;
30 import org.apache.hadoop.hbase.HBaseIOException;
31 import org.apache.hadoop.hbase.HRegionInfo;
32 import org.apache.hadoop.hbase.ServerName;
33 import org.apache.hadoop.hbase.Stoppable;
34 import org.apache.hadoop.hbase.TableName;
35
36 /**
37 * Makes decisions about the placement and movement of Regions across
38 * RegionServers.
39 *
40 * <p>Cluster-wide load balancing will occur only when there are no regions in
41 * transition and according to a fixed period of a time using {@link #balanceCluster(Map)}.
42 *
43 * <p>Inline region placement with {@link #immediateAssignment} can be used when
44 * the Master needs to handle closed regions that it currently does not have
45 * a destination set for. This can happen during master failover.
46 *
47 * <p>On cluster startup, bulk assignment can be used to determine
48 * locations for all Regions in a cluster.
49 *
50 * <p>This classes produces plans for the {@link AssignmentManager} to execute.
51 */
52 @InterfaceAudience.Private
53 public interface LoadBalancer extends Configurable, Stoppable, ConfigurationObserver {
54
55 /**
56 * Set the current cluster status. This allows a LoadBalancer to map host name to a server
57 * @param st
58 */
59 void setClusterStatus(ClusterStatus st);
60
61
62 /**
63 * Set the master service.
64 * @param masterServices
65 */
66 void setMasterServices(MasterServices masterServices);
67
68 /**
69 * Perform the major balance operation
70 * @param tableName
71 * @param clusterState
72 * @return List of plans
73 */
74 List<RegionPlan> balanceCluster(TableName tableName, Map<ServerName,
75 List<HRegionInfo>> clusterState) throws HBaseIOException;
76
77 /**
78 * Perform the major balance operation
79 * @param clusterState
80 * @return List of plans
81 */
82 List<RegionPlan> balanceCluster(Map<ServerName,
83 List<HRegionInfo>> clusterState) throws HBaseIOException;
84
85 /**
86 * Perform a Round Robin assignment of regions.
87 * @param regions
88 * @param servers
89 * @return Map of servername to regioninfos
90 */
91 Map<ServerName, List<HRegionInfo>> roundRobinAssignment(
92 List<HRegionInfo> regions,
93 List<ServerName> servers
94 ) throws HBaseIOException;
95
96 /**
97 * Assign regions to the previously hosting region server
98 * @param regions
99 * @param servers
100 * @return List of plans
101 */
102 Map<ServerName, List<HRegionInfo>> retainAssignment(
103 Map<HRegionInfo, ServerName> regions,
104 List<ServerName> servers
105 ) throws HBaseIOException;
106
107 /**
108 * Sync assign a region
109 * @param regions
110 * @param servers
111 * @return Map regioninfos to servernames
112 */
113 Map<HRegionInfo, ServerName> immediateAssignment(
114 List<HRegionInfo> regions,
115 List<ServerName> servers
116 ) throws HBaseIOException;
117
118 /**
119 * Get a random region server from the list
120 * @param regionInfo Region for which this selection is being done.
121 * @param servers
122 * @return Servername
123 */
124 ServerName randomAssignment(
125 HRegionInfo regionInfo, List<ServerName> servers
126 ) throws HBaseIOException;
127
128 /**
129 * Initialize the load balancer. Must be called after setters.
130 * @throws HBaseIOException
131 */
132 void initialize() throws HBaseIOException;
133
134 /**
135 * Marks the region as online at balancer.
136 * @param regionInfo
137 * @param sn
138 */
139 void regionOnline(HRegionInfo regionInfo, ServerName sn);
140
141 /**
142 * Marks the region as offline at balancer.
143 * @param regionInfo
144 */
145 void regionOffline(HRegionInfo regionInfo);
146
147 /*
148 * Notification that config has changed
149 * @param conf
150 */
151 void onConfigurationChange(Configuration conf);
152
153 /**
154 * If balancer needs to do initialization after Master has started up, lets do that here.
155 */
156 void postMasterStartupInitialize();
157
158 /*Updates balancer status tag reported to JMX*/
159 void updateBalancerStatus(boolean status);
160 }