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 javax.annotation.Nullable;
22 import java.util.List;
23 import java.util.Map;
24
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 @Nullable
103 Map<ServerName, List<HRegionInfo>> retainAssignment(
104 Map<HRegionInfo, ServerName> regions,
105 List<ServerName> servers
106 ) throws HBaseIOException;
107
108 /**
109 * Sync assign a region
110 * @param regions
111 * @param servers
112 * @return Map regioninfos to servernames
113 */
114 Map<HRegionInfo, ServerName> immediateAssignment(
115 List<HRegionInfo> regions,
116 List<ServerName> servers
117 ) throws HBaseIOException;
118
119 /**
120 * Get a random region server from the list
121 * @param regionInfo Region for which this selection is being done.
122 * @param servers
123 * @return Servername
124 */
125 ServerName randomAssignment(
126 HRegionInfo regionInfo, List<ServerName> servers
127 ) throws HBaseIOException;
128
129 /**
130 * Initialize the load balancer. Must be called after setters.
131 * @throws HBaseIOException
132 */
133 void initialize() throws HBaseIOException;
134
135 /**
136 * Marks the region as online at balancer.
137 * @param regionInfo
138 * @param sn
139 */
140 void regionOnline(HRegionInfo regionInfo, ServerName sn);
141
142 /**
143 * Marks the region as offline at balancer.
144 * @param regionInfo
145 */
146 void regionOffline(HRegionInfo regionInfo);
147
148 /*
149 * Notification that config has changed
150 * @param conf
151 */
152 void onConfigurationChange(Configuration conf);
153 }