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.client.coprocessor.Exec; 30 import org.apache.hadoop.hbase.client.coprocessor.ExecResult; 31 import org.apache.hadoop.hbase.security.TokenInfo; 32 import org.apache.hadoop.hbase.security.KerberosInfo; 33 import org.apache.hadoop.hbase.snapshot.HSnapshotDescription; 34 import org.apache.hadoop.hbase.util.Pair; 35 36 /** 37 * Clients interact with the HMasterInterface to gain access to meta-level 38 * HBase functionality, like finding an HRegionServer and creating/destroying 39 * tables. 40 * 41 * <p>NOTE: if you change the interface, you must change the RPC version 42 * number in HBaseRPCProtocolVersion 43 * 44 */ 45 @KerberosInfo( 46 serverPrincipal = "hbase.master.kerberos.principal") 47 @TokenInfo("HBASE_AUTH_TOKEN") 48 public interface HMasterInterface extends VersionedProtocol { 49 /** 50 * This Interfaces' version. Version changes when the Interface changes. 51 */ 52 // All HBase Interfaces used derive from HBaseRPCProtocolVersion. It 53 // maintained a single global version number on all HBase Interfaces. This 54 // meant all HBase RPC was broke though only one of the three RPC Interfaces 55 // had changed. This has since been undone. 56 // 29: 4/3/2010 - changed ClusterStatus serialization 57 // 30: 3/20/2012 - HBASE-5589: Added offline method 58 59 // NOTE: Not bumped from 29 to maintain compatibility since this addition is 60 // after the v0.92.0 releases this is applied to. This is not bumped for 61 // 0.94.0 to maintain rolling restart compatibility with 0.92.x. 62 public static final long VERSION = 29L; 63 64 /** @return true if master is available */ 65 public boolean isMasterRunning(); 66 67 // Admin tools would use these cmds 68 69 /** 70 * Creates a new table asynchronously. If splitKeys are specified, then the 71 * table will be created with an initial set of multiple regions. 72 * If splitKeys is null, the table will be created with a single region. 73 * @param desc table descriptor 74 * @param splitKeys 75 * @throws IOException 76 */ 77 public void createTable(HTableDescriptor desc, byte [][] splitKeys) 78 throws IOException; 79 80 /** 81 * Deletes a table 82 * @param tableName table to delete 83 * @throws IOException e 84 */ 85 public void deleteTable(final byte [] tableName) throws IOException; 86 87 /** 88 * Used by the client to get the number of regions that have received the 89 * updated schema 90 * 91 * @param tableName 92 * @return Pair indicating the number of regions updated Pair.getFirst() is the 93 * regions that are yet to be updated Pair.getSecond() is the total number 94 * of regions of the table 95 * @throws IOException 96 */ 97 public Pair<Integer, Integer> getAlterStatus(byte[] tableName) 98 throws IOException; 99 100 /** 101 * Adds a column to the specified table 102 * @param tableName table to modify 103 * @param column column descriptor 104 * @throws IOException e 105 */ 106 public void addColumn(final byte [] tableName, HColumnDescriptor column) 107 throws IOException; 108 109 /** 110 * Modifies an existing column on the specified table 111 * @param tableName table name 112 * @param descriptor new column descriptor 113 * @throws IOException e 114 */ 115 public void modifyColumn(final byte [] tableName, HColumnDescriptor descriptor) 116 throws IOException; 117 118 119 /** 120 * Deletes a column from the specified table. Table must be disabled. 121 * @param tableName table to alter 122 * @param columnName column family to remove 123 * @throws IOException e 124 */ 125 public void deleteColumn(final byte [] tableName, final byte [] columnName) 126 throws IOException; 127 128 /** 129 * Puts the table on-line (only needed if table has been previously taken offline) 130 * @param tableName table to enable 131 * @throws IOException e 132 */ 133 public void enableTable(final byte [] tableName) throws IOException; 134 135 /** 136 * Take table offline 137 * 138 * @param tableName table to take offline 139 * @throws IOException e 140 */ 141 public void disableTable(final byte [] tableName) throws IOException; 142 143 /** 144 * Modify a table's metadata 145 * 146 * @param tableName table to modify 147 * @param htd new descriptor for table 148 * @throws IOException e 149 */ 150 public void modifyTable(byte[] tableName, HTableDescriptor htd) 151 throws IOException; 152 153 /** 154 * Shutdown an HBase cluster. 155 * @throws IOException e 156 */ 157 public void shutdown() throws IOException; 158 159 /** 160 * Stop HBase Master only. 161 * Does not shutdown the cluster. 162 * @throws IOException e 163 */ 164 public void stopMaster() throws IOException; 165 166 /** 167 * Return cluster status. 168 * @return status object 169 * @throws IOException 170 */ 171 public ClusterStatus getClusterStatus(); 172 173 /** 174 * Move the region <code>r</code> to <code>dest</code>. 175 * @param encodedRegionName The encoded region name; i.e. the hash that makes 176 * up the region name suffix: e.g. if regionname is 177 * <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>, 178 * then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>. 179 * @param destServerName The servername of the destination regionserver. If 180 * passed the empty byte array we'll assign to a random server. A server name 181 * is made of host, port and startcode. Here is an example: 182 * <code> host187.example.com,60020,1289493121758</code>. 183 * @throws UnknownRegionException Thrown if we can't find a region named 184 * <code>encodedRegionName</code> 185 */ 186 public void move(final byte [] encodedRegionName, final byte [] destServerName) 187 throws UnknownRegionException; 188 189 /** 190 * Assign a region to a server chosen at random. 191 * @param regionName Region to assign. Will use existing RegionPlan if one 192 * found. 193 * @param force If true, will force the assignment. 194 * @throws IOException 195 * @deprecated The <code>force</code> is unused.Use {@link #assign(byte[])} 196 */ 197 public void assign(final byte [] regionName, final boolean force) 198 throws IOException; 199 200 /** 201 * Assign a region to a server chosen at random. 202 * 203 * @param regionName 204 * Region to assign. Will use existing RegionPlan if one found. 205 * @throws IOException 206 */ 207 public void assign(final byte[] regionName) throws IOException; 208 209 /** 210 * Unassign a region from current hosting regionserver. Region will then be 211 * assigned to a regionserver chosen at random. Region could be reassigned 212 * back to the same server. Use {@link #move(byte[], byte[])} if you want 213 * to control the region movement. 214 * @param regionName Region to unassign. Will clear any existing RegionPlan 215 * if one found. 216 * @param force If true, force unassign (Will remove region from 217 * regions-in-transition too if present as well as from assigned regions -- 218 * radical!.If results in double assignment use hbck -fix to resolve. 219 * @throws IOException 220 */ 221 public void unassign(final byte [] regionName, final boolean force) 222 throws IOException; 223 224 /** 225 * Offline a region from the assignment manager's in-memory state. The 226 * region should be in a closed state and there will be no attempt to 227 * automatically reassign the region as in unassign. This is a special 228 * method, and should only be used by experts or hbck. 229 * @param regionName Region to offline. Will clear any existing RegionPlan 230 * if one found. 231 * @throws IOException 232 */ 233 public void offline(final byte[] regionName) throws IOException; 234 235 /** 236 * Run the balancer. Will run the balancer and if regions to move, it will 237 * go ahead and do the reassignments. Can NOT run for various reasons. Check 238 * logs. 239 * @return True if balancer ran and was able to tell the region servers to 240 * unassign all the regions to balance (the re-assignment itself is async), 241 * false otherwise. 242 */ 243 public boolean balance(); 244 245 /** 246 * Turn the load balancer on or off. 247 * @param b If true, enable balancer. If false, disable balancer. 248 * @return Previous balancer value 249 */ 250 public boolean balanceSwitch(final boolean b); 251 252 /** 253 * Turn the load balancer on or off. 254 * It waits until current balance() call, if outstanding, to return. 255 * @param b If true, enable balancer. If false, disable balancer. 256 * @return Previous balancer value 257 */ 258 public boolean synchronousBalanceSwitch(final boolean b); 259 260 /** 261 * Get array of all HTDs. 262 * <p> 263 * NOTE: This interface up to and including 0.94.8 included a getHTableDescriptors which 264 * did not throw IOE. Adding and deleting checked exceptions declared as thrown by a method 265 * does not break binary compatibility, so rolling restart scenarios will work; however, 266 * it will break contract compatibility possibly requiring source code changes upon 267 * next recompilation. 268 * @return array of HTableDescriptor 269 */ 270 public HTableDescriptor[] getHTableDescriptors() throws IOException; 271 272 /** 273 * Get array of HTDs for requested tables. 274 * <p> 275 * NOTE: This interface up to and including 0.94.8 included a getHTableDescriptors which 276 * did not throw IOE. Adding and deleting checked exceptions declared as thrown by a method 277 * does not break binary compatibility, so rolling restart scenarios will work; however, 278 * it will break contract compatibility possibly requiring source code changes upon 279 * next recompilation. 280 * @param tableNames 281 * @return array of HTableDescriptor 282 * @throws IOException 283 */ 284 public HTableDescriptor[] getHTableDescriptors(List<String> tableNames) throws IOException; 285 286 /** 287 * Executes a single {@link org.apache.hadoop.hbase.ipc.CoprocessorProtocol} 288 * method using the registered protocol handlers. 289 * {@link CoprocessorProtocol} implementations must be registered via the 290 * {@link org.apache.hadoop.hbase.master.MasterServices#registerProtocol(Class, CoprocessorProtocol)} 291 * method before they are available. 292 * 293 * @param call an {@code Exec} instance identifying the protocol, method name, 294 * and parameters for the method invocation 295 * @return an {@code ExecResult} instance containing the region name of the 296 * invocation and the return value 297 * @throws IOException if no registered protocol handler is found or an error 298 * occurs during the invocation 299 * @see org.apache.hadoop.hbase.master.MasterServices#registerProtocol(Class, CoprocessorProtocol) 300 */ 301 public ExecResult execCoprocessor(Exec call) 302 throws IOException; 303 304 public long snapshot(final HSnapshotDescription snapshot) 305 throws IOException; 306 307 public List<HSnapshotDescription> getCompletedSnapshots() 308 throws IOException; 309 310 public void deleteSnapshot(final HSnapshotDescription snapshot) 311 throws IOException; 312 313 public boolean isSnapshotDone(final HSnapshotDescription snapshot) 314 throws IOException; 315 316 public void restoreSnapshot(final HSnapshotDescription request) 317 throws IOException; 318 319 public boolean isRestoreSnapshotDone(final HSnapshotDescription request) 320 throws IOException; 321 322 /** 323 * Return all table names. 324 * @return the list of table names 325 * @throws IOException if an error occurred while getting the list of tables 326 */ 327 public String[] getTableNames() throws IOException; 328 }