1 /** 2 * Copyright 2010 The Apache Software Foundation 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, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19 */ 20 package org.apache.hadoop.hbase.ipc; 21 22 import java.io.IOException; 23 import java.util.List; 24 25 import org.apache.hadoop.hbase.ClusterStatus; 26 import org.apache.hadoop.hbase.HColumnDescriptor; 27 import org.apache.hadoop.hbase.HTableDescriptor; 28 import org.apache.hadoop.hbase.UnknownRegionException; 29 import org.apache.hadoop.hbase.security.TokenInfo; 30 import org.apache.hadoop.hbase.security.KerberosInfo; 31 import org.apache.hadoop.hbase.util.Pair; 32 33 /** 34 * Clients interact with the HMasterInterface to gain access to meta-level 35 * HBase functionality, like finding an HRegionServer and creating/destroying 36 * tables. 37 * 38 * <p>NOTE: if you change the interface, you must change the RPC version 39 * number in HBaseRPCProtocolVersion 40 * 41 */ 42 @KerberosInfo( 43 serverPrincipal = "hbase.master.kerberos.principal") 44 @TokenInfo("HBASE_AUTH_TOKEN") 45 public interface HMasterInterface extends VersionedProtocol { 46 /** 47 * This Interfaces' version. Version changes when the Interface changes. 48 */ 49 // All HBase Interfaces used derive from HBaseRPCProtocolVersion. It 50 // maintained a single global version number on all HBase Interfaces. This 51 // meant all HBase RPC was broke though only one of the three RPC Interfaces 52 // had changed. This has since been undone. 53 // 29: 4/3/2010 - changed ClusterStatus serialization 54 public static final long VERSION = 29L; 55 56 /** @return true if master is available */ 57 public boolean isMasterRunning(); 58 59 // Admin tools would use these cmds 60 61 /** 62 * Creates a new table asynchronously. If splitKeys are specified, then the 63 * table will be created with an initial set of multiple regions. 64 * If splitKeys is null, the table will be created with a single region. 65 * @param desc table descriptor 66 * @param splitKeys 67 * @throws IOException 68 */ 69 public void createTable(HTableDescriptor desc, byte [][] splitKeys) 70 throws IOException; 71 72 /** 73 * Deletes a table 74 * @param tableName table to delete 75 * @throws IOException e 76 */ 77 public void deleteTable(final byte [] tableName) throws IOException; 78 79 /** 80 * Used by the client to get the number of regions that have received the 81 * updated schema 82 * 83 * @param tableName 84 * @return Pair indicating the number of regions updated Pair.getFirst() is the 85 * regions that are yet to be updated Pair.getSecond() is the total number 86 * of regions of the table 87 * @throws IOException 88 */ 89 public Pair<Integer, Integer> getAlterStatus(byte[] tableName) 90 throws IOException; 91 92 /** 93 * Adds a column to the specified table 94 * @param tableName table to modify 95 * @param column column descriptor 96 * @throws IOException e 97 */ 98 public void addColumn(final byte [] tableName, HColumnDescriptor column) 99 throws IOException; 100 101 /** 102 * Modifies an existing column on the specified table 103 * @param tableName table name 104 * @param descriptor new column descriptor 105 * @throws IOException e 106 */ 107 public void modifyColumn(final byte [] tableName, HColumnDescriptor descriptor) 108 throws IOException; 109 110 111 /** 112 * Deletes a column from the specified table. Table must be disabled. 113 * @param tableName table to alter 114 * @param columnName column family to remove 115 * @throws IOException e 116 */ 117 public void deleteColumn(final byte [] tableName, final byte [] columnName) 118 throws IOException; 119 120 /** 121 * Puts the table on-line (only needed if table has been previously taken offline) 122 * @param tableName table to enable 123 * @throws IOException e 124 */ 125 public void enableTable(final byte [] tableName) throws IOException; 126 127 /** 128 * Take table offline 129 * 130 * @param tableName table to take offline 131 * @throws IOException e 132 */ 133 public void disableTable(final byte [] tableName) throws IOException; 134 135 /** 136 * Modify a table's metadata 137 * 138 * @param tableName table to modify 139 * @param htd new descriptor for table 140 * @throws IOException e 141 */ 142 public void modifyTable(byte[] tableName, HTableDescriptor htd) 143 throws IOException; 144 145 /** 146 * Shutdown an HBase cluster. 147 * @throws IOException e 148 */ 149 public void shutdown() throws IOException; 150 151 /** 152 * Stop HBase Master only. 153 * Does not shutdown the cluster. 154 * @throws IOException e 155 */ 156 public void stopMaster() throws IOException; 157 158 /** 159 * Return cluster status. 160 * @return status object 161 */ 162 public ClusterStatus getClusterStatus(); 163 164 165 /** 166 * Move the region <code>r</code> to <code>dest</code>. 167 * @param encodedRegionName The encoded region name; i.e. the hash that makes 168 * up the region name suffix: e.g. if regionname is 169 * <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>, 170 * then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>. 171 * @param destServerName The servername of the destination regionserver. If 172 * passed the empty byte array we'll assign to a random server. A server name 173 * is made of host, port and startcode. Here is an example: 174 * <code> host187.example.com,60020,1289493121758</code>. 175 * @throws UnknownRegionException Thrown if we can't find a region named 176 * <code>encodedRegionName</code> 177 */ 178 public void move(final byte [] encodedRegionName, final byte [] destServerName) 179 throws UnknownRegionException; 180 181 /** 182 * Assign a region to a server chosen at random. 183 * @param regionName Region to assign. Will use existing RegionPlan if one 184 * found. 185 * @param force If true, will force the assignment. 186 * @throws IOException 187 * @deprecated The <code>force</code> is unused.Use {@link #assign(byte[])} 188 */ 189 public void assign(final byte [] regionName, final boolean force) 190 throws IOException; 191 192 /** 193 * Assign a region to a server chosen at random. 194 * 195 * @param regionName 196 * Region to assign. Will use existing RegionPlan if one found. 197 * @throws IOException 198 */ 199 public void assign(final byte[] regionName) throws IOException; 200 201 /** 202 * Unassign a region from current hosting regionserver. Region will then be 203 * assigned to a regionserver chosen at random. Region could be reassigned 204 * back to the same server. Use {@link #move(byte[], byte[])} if you want 205 * to control the region movement. 206 * @param regionName Region to unassign. Will clear any existing RegionPlan 207 * if one found. 208 * @param force If true, force unassign (Will remove region from 209 * regions-in-transition too if present as well as from assigned regions -- 210 * radical!.If results in double assignment use hbck -fix to resolve. 211 * @throws IOException 212 */ 213 public void unassign(final byte [] regionName, final boolean force) 214 throws IOException; 215 216 /** 217 * Run the balancer. Will run the balancer and if regions to move, it will 218 * go ahead and do the reassignments. Can NOT run for various reasons. Check 219 * logs. 220 * @return True if balancer ran and was able to tell the region servers to 221 * unassign all the regions to balance (the re-assignment itself is async), 222 * false otherwise. 223 */ 224 public boolean balance(); 225 226 /** 227 * Turn the load balancer on or off. 228 * @param b If true, enable balancer. If false, disable balancer. 229 * @return Previous balancer value 230 */ 231 public boolean balanceSwitch(final boolean b); 232 233 /** 234 * Get array of all HTDs. 235 * @return array of HTableDescriptor 236 */ 237 public HTableDescriptor[] getHTableDescriptors(); 238 239 /** 240 * Get current HTD for a given tablename 241 * @param tableName 242 * @return HTableDescriptor for the table 243 */ 244 //public HTableDescriptor getHTableDescriptor(final byte[] tableName); 245 246 /** 247 * Get array of HTDs for requested tables. 248 * @param tableNames 249 * @return array of HTableDescriptor 250 */ 251 public HTableDescriptor[] getHTableDescriptors(List<String> tableNames); 252 253 }