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  String TABLES_ON_MASTER = "hbase.balancer.tablesOnMaster";
057
058  /**
059   * Master carries system tables.
060   */
061  String SYSTEM_TABLES_ON_MASTER = "hbase.balancer.tablesOnMaster.systemTablesOnly";
062
063  // Used to signal to the caller that the region(s) cannot be assigned
064  // We deliberately use 'localhost' so the operation will fail fast
065  ServerName BOGUS_SERVER_NAME = ServerName.valueOf("localhost,1,1");
066
067  /**
068   * Set the current cluster status.  This allows a LoadBalancer to map host name to a server
069   * @param st
070   */
071  void setClusterMetrics(ClusterMetrics st);
072
073  /**
074   * Pass RegionStates and allow balancer to set the current cluster load.
075   * @param ClusterLoad
076   */
077  void setClusterLoad(Map<TableName, Map<ServerName, List<RegionInfo>>> ClusterLoad);
078
079  /**
080   * Set the master service.
081   * @param masterServices
082   */
083  void setMasterServices(MasterServices masterServices);
084
085  /**
086   * Perform the major balance operation
087   * @param tableName
088   * @param clusterState
089   * @return List of plans
090   */
091  List<RegionPlan> balanceCluster(TableName tableName, Map<ServerName,
092      List<RegionInfo>> clusterState) throws HBaseIOException;
093
094  /**
095   * Perform the major balance operation
096   * @param clusterState
097   * @return List of plans
098   */
099  List<RegionPlan> balanceCluster(Map<ServerName,
100      List<RegionInfo>> clusterState) throws HBaseIOException;
101
102  /**
103   * Perform a Round Robin assignment of regions.
104   * @param regions
105   * @param servers
106   * @return Map of servername to regioninfos
107   */
108  Map<ServerName, List<RegionInfo>> roundRobinAssignment(
109    List<RegionInfo> regions,
110    List<ServerName> servers
111  ) throws HBaseIOException;
112
113  /**
114   * Assign regions to the previously hosting region server
115   * @param regions
116   * @param servers
117   * @return List of plans
118   */
119  @Nullable
120  Map<ServerName, List<RegionInfo>> retainAssignment(
121    Map<RegionInfo, ServerName> regions,
122    List<ServerName> servers
123  ) throws HBaseIOException;
124
125  /**
126   * Get a random region server from the list
127   * @param regionInfo Region for which this selection is being done.
128   * @param servers
129   * @return Servername
130   */
131  ServerName randomAssignment(
132    RegionInfo regionInfo, List<ServerName> servers
133  ) throws HBaseIOException;
134
135  /**
136   * Initialize the load balancer. Must be called after setters.
137   * @throws HBaseIOException
138   */
139  void initialize() throws HBaseIOException;
140
141  /**
142   * Marks the region as online at balancer.
143   * @param regionInfo
144   * @param sn
145   */
146  void regionOnline(RegionInfo regionInfo, ServerName sn);
147
148  /**
149   * Marks the region as offline at balancer.
150   * @param regionInfo
151   */
152  void regionOffline(RegionInfo regionInfo);
153
154  /*
155   * Notification that config has changed
156   * @param conf
157   */
158  @Override
159  void onConfigurationChange(Configuration conf);
160
161  /**
162   * If balancer needs to do initialization after Master has started up, lets do that here.
163   */
164  void postMasterStartupInitialize();
165
166  /**
167   * @return true if Master carries regions
168   */
169  static boolean isTablesOnMaster(Configuration conf) {
170    return conf.getBoolean(TABLES_ON_MASTER, false);
171  }
172
173  static boolean isSystemTablesOnlyOnMaster(Configuration conf) {
174    return conf.getBoolean(SYSTEM_TABLES_ON_MASTER, false);
175  }
176
177  static boolean isMasterCanHostUserRegions(Configuration conf) {
178    return isTablesOnMaster(conf) && !isSystemTablesOnlyOnMaster(conf);
179  }
180}