001/**
002 *
003 * Licensed to the Apache Software Foundation (ASF) under one
004 * or more contributor license agreements.  See the NOTICE file
005 * distributed with this work for additional information
006 * regarding copyright ownership.  The ASF licenses this file
007 * to you under the Apache License, Version 2.0 (the
008 * "License"); you may not use this file except in compliance
009 * with the License.  You may obtain a copy of the License at
010 *
011 *     http://www.apache.org/licenses/LICENSE-2.0
012 *
013 * Unless required by applicable law or agreed to in writing, software
014 * distributed under the License is distributed on an "AS IS" BASIS,
015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016 * See the License for the specific language governing permissions and
017 * limitations under the License.
018 */
019package org.apache.hadoop.hbase.master;
020
021import edu.umd.cs.findbugs.annotations.Nullable;
022import java.util.List;
023import java.util.Map;
024import org.apache.hadoop.conf.Configurable;
025import org.apache.hadoop.conf.Configuration;
026import org.apache.hadoop.hbase.ClusterMetrics;
027import org.apache.hadoop.hbase.HBaseIOException;
028import org.apache.hadoop.hbase.ServerName;
029import org.apache.hadoop.hbase.Stoppable;
030import org.apache.hadoop.hbase.TableName;
031import org.apache.hadoop.hbase.client.RegionInfo;
032import org.apache.hadoop.hbase.conf.ConfigurationObserver;
033import org.apache.yetus.audience.InterfaceAudience;
034
035/**
036 * Makes decisions about the placement and movement of Regions across
037 * RegionServers.
038 *
039 * <p>Cluster-wide load balancing will occur only when there are no regions in
040 * transition and according to a fixed period of a time using {@link #balanceCluster(Map)}.
041 *
042 * <p>On cluster startup, bulk assignment can be used to determine
043 * locations for all Regions in a cluster.
044 *
045 * <p>This class produces plans for the
046 * {@link org.apache.hadoop.hbase.master.assignment.AssignmentManager}
047 * to execute.
048 */
049@InterfaceAudience.Private
050public interface LoadBalancer extends Configurable, Stoppable, ConfigurationObserver {
051  /**
052   * Master can carry regions as of hbase-2.0.0.
053   * By default, it carries no tables.
054   * TODO: Add any | system as flags to indicate what it can do.
055   */
056  public static final String TABLES_ON_MASTER = "hbase.balancer.tablesOnMaster";
057
058  /**
059   * Master carries system tables.
060   */
061  public static final String SYSTEM_TABLES_ON_MASTER =
062    "hbase.balancer.tablesOnMaster.systemTablesOnly";
063
064  // Used to signal to the caller that the region(s) cannot be assigned
065  // We deliberately use 'localhost' so the operation will fail fast
066  ServerName BOGUS_SERVER_NAME = ServerName.valueOf("localhost,1,1");
067
068  /**
069   * Set the current cluster status.  This allows a LoadBalancer to map host name to a server
070   * @param st
071   */
072  void setClusterMetrics(ClusterMetrics st);
073
074  /**
075   * Pass RegionStates and allow balancer to set the current cluster load.
076   * @param ClusterLoad
077   */
078  void setClusterLoad(Map<TableName, Map<ServerName, List<RegionInfo>>> ClusterLoad);
079
080  /**
081   * Set the master service.
082   * @param masterServices
083   */
084  void setMasterServices(MasterServices masterServices);
085
086  /**
087   * Perform the major balance operation
088   * @param tableName
089   * @param clusterState
090   * @return List of plans
091   */
092  List<RegionPlan> balanceCluster(TableName tableName, Map<ServerName,
093      List<RegionInfo>> clusterState) throws HBaseIOException;
094
095  /**
096   * Perform the major balance operation
097   * @param clusterState
098   * @return List of plans
099   */
100  List<RegionPlan> balanceCluster(Map<ServerName,
101      List<RegionInfo>> clusterState) throws HBaseIOException;
102
103  /**
104   * Perform a Round Robin assignment of regions.
105   * @param regions
106   * @param servers
107   * @return Map of servername to regioninfos
108   */
109  Map<ServerName, List<RegionInfo>> roundRobinAssignment(
110    List<RegionInfo> regions,
111    List<ServerName> servers
112  ) throws HBaseIOException;
113
114  /**
115   * Assign regions to the previously hosting region server
116   * @param regions
117   * @param servers
118   * @return List of plans
119   */
120  @Nullable
121  Map<ServerName, List<RegionInfo>> retainAssignment(
122    Map<RegionInfo, ServerName> regions,
123    List<ServerName> servers
124  ) throws HBaseIOException;
125
126  /**
127   * Get a random region server from the list
128   * @param regionInfo Region for which this selection is being done.
129   * @param servers
130   * @return Servername
131   */
132  ServerName randomAssignment(
133    RegionInfo regionInfo, List<ServerName> servers
134  ) throws HBaseIOException;
135
136  /**
137   * Initialize the load balancer. Must be called after setters.
138   * @throws HBaseIOException
139   */
140  void initialize() throws HBaseIOException;
141
142  /**
143   * Marks the region as online at balancer.
144   * @param regionInfo
145   * @param sn
146   */
147  void regionOnline(RegionInfo regionInfo, ServerName sn);
148
149  /**
150   * Marks the region as offline at balancer.
151   * @param regionInfo
152   */
153  void regionOffline(RegionInfo regionInfo);
154
155  /*
156   * Notification that config has changed
157   * @param conf
158   */
159  @Override
160  void onConfigurationChange(Configuration conf);
161
162  /**
163   * If balancer needs to do initialization after Master has started up, lets do that here.
164   */
165  void postMasterStartupInitialize();
166
167  /**
168   * @return true if Master carries regions
169   */
170  static boolean isTablesOnMaster(Configuration conf) {
171    return conf.getBoolean(TABLES_ON_MASTER, false);
172  }
173
174  static boolean isSystemTablesOnlyOnMaster(Configuration conf) {
175    return conf.getBoolean(SYSTEM_TABLES_ON_MASTER, false);
176  }
177}