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.client; 20 21 import java.io.Closeable; 22 import java.io.IOException; 23 import java.util.List; 24 import java.util.Map; 25 import java.util.concurrent.Future; 26 import java.util.regex.Pattern; 27 28 import org.apache.hadoop.conf.Configuration; 29 import org.apache.hadoop.hbase.Abortable; 30 import org.apache.hadoop.hbase.ClusterStatus; 31 import org.apache.hadoop.hbase.HColumnDescriptor; 32 import org.apache.hadoop.hbase.HRegionInfo; 33 import org.apache.hadoop.hbase.HTableDescriptor; 34 import org.apache.hadoop.hbase.NamespaceDescriptor; 35 import org.apache.hadoop.hbase.ProcedureInfo; 36 import org.apache.hadoop.hbase.ServerName; 37 import org.apache.hadoop.hbase.TableExistsException; 38 import org.apache.hadoop.hbase.TableName; 39 import org.apache.hadoop.hbase.TableNotFoundException; 40 import org.apache.hadoop.hbase.classification.InterfaceAudience; 41 import org.apache.hadoop.hbase.classification.InterfaceStability; 42 import org.apache.hadoop.hbase.client.security.SecurityCapability; 43 import org.apache.hadoop.hbase.ipc.CoprocessorRpcChannel; 44 import org.apache.hadoop.hbase.protobuf.generated.AdminProtos; 45 import org.apache.hadoop.hbase.protobuf.generated.HBaseProtos; 46 import org.apache.hadoop.hbase.protobuf.generated.MasterProtos; 47 import org.apache.hadoop.hbase.quotas.QuotaFilter; 48 import org.apache.hadoop.hbase.quotas.QuotaRetriever; 49 import org.apache.hadoop.hbase.quotas.QuotaSettings; 50 import org.apache.hadoop.hbase.regionserver.wal.FailedLogCloseException; 51 import org.apache.hadoop.hbase.snapshot.HBaseSnapshotException; 52 import org.apache.hadoop.hbase.snapshot.RestoreSnapshotException; 53 import org.apache.hadoop.hbase.snapshot.SnapshotCreationException; 54 import org.apache.hadoop.hbase.snapshot.UnknownSnapshotException; 55 import org.apache.hadoop.hbase.util.Pair; 56 57 /** 58 * The administrative API for HBase. Obtain an instance from an {@link Connection#getAdmin()} and 59 * call {@link #close()} afterwards. 60 * <p>Admin can be used to create, drop, list, enable and disable tables, add and drop table 61 * column families and other administrative operations. 62 * 63 * @see ConnectionFactory 64 * @see Connection 65 * @see Table 66 * @since 0.99.0 67 */ 68 @InterfaceAudience.Public 69 @InterfaceStability.Evolving 70 public interface Admin extends Abortable, Closeable { 71 int getOperationTimeout(); 72 73 @Override 74 void abort(String why, Throwable e); 75 76 @Override 77 boolean isAborted(); 78 79 /** 80 * @return Connection used by this object. 81 */ 82 Connection getConnection(); 83 84 /** 85 * @param tableName Table to check. 86 * @return True if table exists already. 87 * @throws IOException 88 */ 89 boolean tableExists(final TableName tableName) throws IOException; 90 91 /** 92 * List all the userspace tables. 93 * 94 * @return - returns an array of HTableDescriptors 95 * @throws IOException if a remote or network exception occurs 96 */ 97 HTableDescriptor[] listTables() throws IOException; 98 99 /** 100 * List all the userspace tables matching the given pattern. 101 * 102 * @param pattern The compiled regular expression to match against 103 * @return - returns an array of HTableDescriptors 104 * @throws IOException if a remote or network exception occurs 105 * @see #listTables() 106 */ 107 HTableDescriptor[] listTables(Pattern pattern) throws IOException; 108 109 /** 110 * List all the userspace tables matching the given regular expression. 111 * 112 * @param regex The regular expression to match against 113 * @return - returns an array of HTableDescriptors 114 * @throws IOException if a remote or network exception occurs 115 * @see #listTables(java.util.regex.Pattern) 116 */ 117 HTableDescriptor[] listTables(String regex) throws IOException; 118 119 /** 120 * List all the tables matching the given pattern. 121 * 122 * @param pattern The compiled regular expression to match against 123 * @param includeSysTables False to match only against userspace tables 124 * @return - returns an array of HTableDescriptors 125 * @throws IOException if a remote or network exception occurs 126 * @see #listTables() 127 */ 128 HTableDescriptor[] listTables(Pattern pattern, boolean includeSysTables) 129 throws IOException; 130 131 /** 132 * List all the tables matching the given pattern. 133 * 134 * @param regex The regular expression to match against 135 * @param includeSysTables False to match only against userspace tables 136 * @return - returns an array of HTableDescriptors 137 * @throws IOException if a remote or network exception occurs 138 * @see #listTables(java.util.regex.Pattern, boolean) 139 */ 140 HTableDescriptor[] listTables(String regex, boolean includeSysTables) 141 throws IOException; 142 143 /** 144 * List all of the names of userspace tables. 145 * 146 * @return TableName[] table names 147 * @throws IOException if a remote or network exception occurs 148 */ 149 TableName[] listTableNames() throws IOException; 150 151 /** 152 * List all of the names of userspace tables. 153 * @param pattern The regular expression to match against 154 * @return TableName[] table names 155 * @throws IOException if a remote or network exception occurs 156 */ 157 TableName[] listTableNames(Pattern pattern) throws IOException; 158 159 /** 160 * List all of the names of userspace tables. 161 * @param regex The regular expression to match against 162 * @return TableName[] table names 163 * @throws IOException if a remote or network exception occurs 164 */ 165 TableName[] listTableNames(String regex) throws IOException; 166 167 /** 168 * List all of the names of userspace tables. 169 * @param pattern The regular expression to match against 170 * @param includeSysTables False to match only against userspace tables 171 * @return TableName[] table names 172 * @throws IOException if a remote or network exception occurs 173 */ 174 TableName[] listTableNames(final Pattern pattern, final boolean includeSysTables) 175 throws IOException; 176 177 /** 178 * List all of the names of userspace tables. 179 * @param regex The regular expression to match against 180 * @param includeSysTables False to match only against userspace tables 181 * @return TableName[] table names 182 * @throws IOException if a remote or network exception occurs 183 */ 184 TableName[] listTableNames(final String regex, final boolean includeSysTables) 185 throws IOException; 186 187 /** 188 * Method for getting the tableDescriptor 189 * 190 * @param tableName as a {@link TableName} 191 * @return the tableDescriptor 192 * @throws org.apache.hadoop.hbase.TableNotFoundException 193 * @throws IOException if a remote or network exception occurs 194 */ 195 HTableDescriptor getTableDescriptor(final TableName tableName) 196 throws TableNotFoundException, IOException; 197 198 /** 199 * Creates a new table. Synchronous operation. 200 * 201 * @param desc table descriptor for table 202 * @throws IllegalArgumentException if the table name is reserved 203 * @throws org.apache.hadoop.hbase.MasterNotRunningException if master is not running 204 * @throws org.apache.hadoop.hbase.TableExistsException if table already exists (If concurrent 205 * threads, the table may have been created between test-for-existence and attempt-at-creation). 206 * @throws IOException if a remote or network exception occurs 207 */ 208 void createTable(HTableDescriptor desc) throws IOException; 209 210 /** 211 * Creates a new table with the specified number of regions. The start key specified will become 212 * the end key of the first region of the table, and the end key specified will become the start 213 * key of the last region of the table (the first region has a null start key and the last region 214 * has a null end key). BigInteger math will be used to divide the key range specified into enough 215 * segments to make the required number of total regions. Synchronous operation. 216 * 217 * @param desc table descriptor for table 218 * @param startKey beginning of key range 219 * @param endKey end of key range 220 * @param numRegions the total number of regions to create 221 * @throws IllegalArgumentException if the table name is reserved 222 * @throws org.apache.hadoop.hbase.MasterNotRunningException if master is not running 223 * @throws org.apache.hadoop.hbase.TableExistsException if table already exists (If concurrent 224 * threads, the table may have been created between test-for-existence and attempt-at-creation). 225 * @throws IOException 226 */ 227 void createTable(HTableDescriptor desc, byte[] startKey, byte[] endKey, int numRegions) 228 throws IOException; 229 230 /** 231 * Creates a new table with an initial set of empty regions defined by the specified split keys. 232 * The total number of regions created will be the number of split keys plus one. Synchronous 233 * operation. Note : Avoid passing empty split key. 234 * 235 * @param desc table descriptor for table 236 * @param splitKeys array of split keys for the initial regions of the table 237 * @throws IllegalArgumentException if the table name is reserved, if the split keys are repeated 238 * and if the split key has empty byte array. 239 * @throws org.apache.hadoop.hbase.MasterNotRunningException if master is not running 240 * @throws org.apache.hadoop.hbase.TableExistsException if table already exists (If concurrent 241 * threads, the table may have been created between test-for-existence and attempt-at-creation). 242 * @throws IOException 243 */ 244 void createTable(final HTableDescriptor desc, byte[][] splitKeys) throws IOException; 245 246 /** 247 * Creates a new table but does not block and wait for it to come online. 248 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 249 * It may throw ExecutionException if there was an error while executing the operation 250 * or TimeoutException in case the wait timeout was not long enough to allow the 251 * operation to complete. 252 * Throws IllegalArgumentException Bad table name, if the split keys 253 * are repeated and if the split key has empty byte array. 254 * 255 * @param desc table descriptor for table 256 * @param splitKeys keys to check if the table has been created with all split keys 257 * @throws IOException if a remote or network exception occurs 258 * @return the result of the async creation. You can use Future.get(long, TimeUnit) 259 * to wait on the operation to complete. 260 */ 261 Future<Void> createTableAsync(final HTableDescriptor desc, final byte[][] splitKeys) 262 throws IOException; 263 264 /** 265 * Deletes a table. Synchronous operation. 266 * 267 * @param tableName name of table to delete 268 * @throws IOException if a remote or network exception occurs 269 */ 270 void deleteTable(final TableName tableName) throws IOException; 271 272 /** 273 * Deletes the table but does not block and wait for it be completely removed. 274 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 275 * It may throw ExecutionException if there was an error while executing the operation 276 * or TimeoutException in case the wait timeout was not long enough to allow the 277 * operation to complete. 278 * 279 * @param tableName name of table to delete 280 * @throws IOException if a remote or network exception occurs 281 * @return the result of the async delete. You can use Future.get(long, TimeUnit) 282 * to wait on the operation to complete. 283 */ 284 Future<Void> deleteTableAsync(TableName tableName) throws IOException; 285 286 /** 287 * Deletes tables matching the passed in pattern and wait on completion. Warning: Use this method 288 * carefully, there is no prompting and the effect is immediate. Consider using {@link 289 * #listTables(java.lang.String)} and {@link #deleteTable(org.apache.hadoop.hbase.TableName)} 290 * 291 * @param regex The regular expression to match table names against 292 * @return Table descriptors for tables that couldn't be deleted 293 * @throws IOException 294 * @see #deleteTables(java.util.regex.Pattern) 295 * @see #deleteTable(org.apache.hadoop.hbase.TableName) 296 */ 297 HTableDescriptor[] deleteTables(String regex) throws IOException; 298 299 /** 300 * Delete tables matching the passed in pattern and wait on completion. Warning: Use this method 301 * carefully, there is no prompting and the effect is immediate. Consider using {@link 302 * #listTables(java.util.regex.Pattern) } and 303 * {@link #deleteTable(org.apache.hadoop.hbase.TableName)} 304 * 305 * @param pattern The pattern to match table names against 306 * @return Table descriptors for tables that couldn't be deleted 307 * @throws IOException 308 */ 309 HTableDescriptor[] deleteTables(Pattern pattern) throws IOException; 310 311 /** 312 * Truncate a table. 313 * Synchronous operation. 314 * 315 * @param tableName name of table to truncate 316 * @param preserveSplits True if the splits should be preserved 317 * @throws IOException if a remote or network exception occurs 318 */ 319 public void truncateTable(final TableName tableName, final boolean preserveSplits) 320 throws IOException; 321 322 /** 323 * Truncate the table but does not block and wait for it be completely enabled. You can use 324 * Future.get(long, TimeUnit) to wait on the operation to complete. It may throw 325 * ExecutionException if there was an error while executing the operation or TimeoutException in 326 * case the wait timeout was not long enough to allow the operation to complete. 327 * @param tableName name of table to delete 328 * @param preserveSplits true if the splits should be preserved 329 * @throws IOException if a remote or network exception occurs 330 * @return the result of the async truncate. You can use Future.get(long, TimeUnit) to wait on the 331 * operation to complete. 332 */ 333 Future<Void> truncateTableAsync(final TableName tableName, final boolean preserveSplits) 334 throws IOException; 335 336 /** 337 * Enable a table. May timeout. Use {@link #enableTableAsync(org.apache.hadoop.hbase.TableName)} 338 * and {@link #isTableEnabled(org.apache.hadoop.hbase.TableName)} instead. The table has to be in 339 * disabled state for it to be enabled. 340 * 341 * @param tableName name of the table 342 * @throws IOException if a remote or network exception occurs There could be couple types of 343 * IOException TableNotFoundException means the table doesn't exist. TableNotDisabledException 344 * means the table isn't in disabled state. 345 * @see #isTableEnabled(org.apache.hadoop.hbase.TableName) 346 * @see #disableTable(org.apache.hadoop.hbase.TableName) 347 * @see #enableTableAsync(org.apache.hadoop.hbase.TableName) 348 */ 349 void enableTable(final TableName tableName) throws IOException; 350 351 /** 352 * Enable the table but does not block and wait for it be completely enabled. 353 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 354 * It may throw ExecutionException if there was an error while executing the operation 355 * or TimeoutException in case the wait timeout was not long enough to allow the 356 * operation to complete. 357 * 358 * @param tableName name of table to delete 359 * @throws IOException if a remote or network exception occurs 360 * @return the result of the async enable. You can use Future.get(long, TimeUnit) 361 * to wait on the operation to complete. 362 */ 363 Future<Void> enableTableAsync(final TableName tableName) throws IOException; 364 365 /** 366 * Enable tables matching the passed in pattern and wait on completion. Warning: Use this method 367 * carefully, there is no prompting and the effect is immediate. Consider using {@link 368 * #listTables(java.lang.String)} and {@link #enableTable(org.apache.hadoop.hbase.TableName)} 369 * 370 * @param regex The regular expression to match table names against 371 * @throws IOException 372 * @see #enableTables(java.util.regex.Pattern) 373 * @see #enableTable(org.apache.hadoop.hbase.TableName) 374 */ 375 HTableDescriptor[] enableTables(String regex) throws IOException; 376 377 /** 378 * Enable tables matching the passed in pattern and wait on completion. Warning: Use this method 379 * carefully, there is no prompting and the effect is immediate. Consider using {@link 380 * #listTables(java.util.regex.Pattern) } and 381 * {@link #enableTable(org.apache.hadoop.hbase.TableName)} 382 * 383 * @param pattern The pattern to match table names against 384 * @throws IOException 385 */ 386 HTableDescriptor[] enableTables(Pattern pattern) throws IOException; 387 388 /** 389 * Disable the table but does not block and wait for it be completely disabled. 390 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 391 * It may throw ExecutionException if there was an error while executing the operation 392 * or TimeoutException in case the wait timeout was not long enough to allow the 393 * operation to complete. 394 * 395 * @param tableName name of table to delete 396 * @throws IOException if a remote or network exception occurs 397 * @return the result of the async disable. You can use Future.get(long, TimeUnit) 398 * to wait on the operation to complete. 399 */ 400 Future<Void> disableTableAsync(final TableName tableName) throws IOException; 401 402 /** 403 * Disable table and wait on completion. May timeout eventually. Use {@link 404 * #disableTableAsync(org.apache.hadoop.hbase.TableName)} and 405 * {@link #isTableDisabled(org.apache.hadoop.hbase.TableName)} instead. The table has to be in 406 * enabled state for it to be disabled. 407 * 408 * @param tableName 409 * @throws IOException There could be couple types of IOException TableNotFoundException means the 410 * table doesn't exist. TableNotEnabledException means the table isn't in enabled state. 411 */ 412 void disableTable(final TableName tableName) throws IOException; 413 414 /** 415 * Disable tables matching the passed in pattern and wait on completion. Warning: Use this method 416 * carefully, there is no prompting and the effect is immediate. Consider using {@link 417 * #listTables(java.lang.String)} and {@link #disableTable(org.apache.hadoop.hbase.TableName)} 418 * 419 * @param regex The regular expression to match table names against 420 * @return Table descriptors for tables that couldn't be disabled 421 * @throws IOException 422 * @see #disableTables(java.util.regex.Pattern) 423 * @see #disableTable(org.apache.hadoop.hbase.TableName) 424 */ 425 HTableDescriptor[] disableTables(String regex) throws IOException; 426 427 /** 428 * Disable tables matching the passed in pattern and wait on completion. Warning: Use this method 429 * carefully, there is no prompting and the effect is immediate. Consider using {@link 430 * #listTables(java.util.regex.Pattern) } and 431 * {@link #disableTable(org.apache.hadoop.hbase.TableName)} 432 * 433 * @param pattern The pattern to match table names against 434 * @return Table descriptors for tables that couldn't be disabled 435 * @throws IOException 436 */ 437 HTableDescriptor[] disableTables(Pattern pattern) throws IOException; 438 439 /** 440 * @param tableName name of table to check 441 * @return true if table is on-line 442 * @throws IOException if a remote or network exception occurs 443 */ 444 boolean isTableEnabled(TableName tableName) throws IOException; 445 446 /** 447 * @param tableName name of table to check 448 * @return true if table is off-line 449 * @throws IOException if a remote or network exception occurs 450 */ 451 boolean isTableDisabled(TableName tableName) throws IOException; 452 453 /** 454 * @param tableName name of table to check 455 * @return true if all regions of the table are available 456 * @throws IOException if a remote or network exception occurs 457 */ 458 boolean isTableAvailable(TableName tableName) throws IOException; 459 460 /** 461 * Use this api to check if the table has been created with the specified number of splitkeys 462 * which was used while creating the given table. Note : If this api is used after a table's 463 * region gets splitted, the api may return false. 464 * 465 * @param tableName name of table to check 466 * @param splitKeys keys to check if the table has been created with all split keys 467 * @throws IOException if a remote or network excpetion occurs 468 */ 469 boolean isTableAvailable(TableName tableName, byte[][] splitKeys) throws IOException; 470 471 /** 472 * Get the status of alter command - indicates how many regions have received the updated schema 473 * Asynchronous operation. 474 * 475 * @param tableName TableName instance 476 * @return Pair indicating the number of regions updated Pair.getFirst() is the regions that are 477 * yet to be updated Pair.getSecond() is the total number of regions of the table 478 * @throws IOException if a remote or network exception occurs 479 */ 480 Pair<Integer, Integer> getAlterStatus(final TableName tableName) throws IOException; 481 482 /** 483 * Get the status of alter command - indicates how many regions have received the updated schema 484 * Asynchronous operation. 485 * 486 * @param tableName name of the table to get the status of 487 * @return Pair indicating the number of regions updated Pair.getFirst() is the regions that are 488 * yet to be updated Pair.getSecond() is the total number of regions of the table 489 * @throws IOException if a remote or network exception occurs 490 */ 491 Pair<Integer, Integer> getAlterStatus(final byte[] tableName) throws IOException; 492 493 /** 494 * Add a column family to an existing table. Asynchronous operation. 495 * 496 * @param tableName name of the table to add column family to 497 * @param columnFamily column family descriptor of column family to be added 498 * @throws IOException if a remote or network exception occurs 499 * @deprecated As of release 2.0.0. 500 * (<a href="https://issues.apache.org/jira/browse/HBASE-1989">HBASE-1989</a>). 501 * This will be removed in HBase 3.0.0. 502 * Use {@link #addColumnFamily(TableName, HColumnDescriptor)}. 503 */ 504 @Deprecated 505 void addColumn(final TableName tableName, final HColumnDescriptor columnFamily) 506 throws IOException; 507 508 /** 509 * Add a column family to an existing table. Asynchronous operation. 510 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 511 * It may throw ExecutionException if there was an error while executing the operation 512 * or TimeoutException in case the wait timeout was not long enough to allow the 513 * operation to complete. 514 * 515 * @param tableName name of the table to add column family to 516 * @param columnFamily column family descriptor of column family to be added 517 * @throws IOException if a remote or network exception occurs 518 * @return the result of the async add column family. You can use Future.get(long, TimeUnit) to 519 * wait on the operation to complete. 520 */ 521 Future<Void> addColumnFamily(final TableName tableName, final HColumnDescriptor columnFamily) 522 throws IOException; 523 524 /** 525 * Delete a column family from a table. Asynchronous operation. 526 * 527 * @param tableName name of table 528 * @param columnFamily name of column family to be deleted 529 * @throws IOException if a remote or network exception occurs 530 * @deprecated As of release 2.0.0. 531 * (<a href="https://issues.apache.org/jira/browse/HBASE-1989">HBASE-1989</a>). 532 * This will be removed in HBase 3.0.0. 533 * Use {@link #deleteColumnFamily(TableName, byte[])}}. 534 */ 535 @Deprecated 536 void deleteColumn(final TableName tableName, final byte[] columnFamily) throws IOException; 537 538 /** 539 * Delete a column family from a table. Asynchronous operation. 540 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 541 * It may throw ExecutionException if there was an error while executing the operation 542 * or TimeoutException in case the wait timeout was not long enough to allow the 543 * operation to complete. 544 * 545 * @param tableName name of table 546 * @param columnFamily name of column family to be deleted 547 * @throws IOException if a remote or network exception occurs 548 * @return the result of the async delete column family. You can use Future.get(long, TimeUnit) to 549 * wait on the operation to complete. 550 */ 551 Future<Void> deleteColumnFamily(final TableName tableName, final byte[] columnFamily) 552 throws IOException; 553 554 /** 555 * Modify an existing column family on a table. Asynchronous operation. 556 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 557 * It may throw ExecutionException if there was an error while executing the operation 558 * or TimeoutException in case the wait timeout was not long enough to allow the 559 * operation to complete. 560 * 561 * @param tableName name of table 562 * @param columnFamily new column family descriptor to use 563 * @throws IOException if a remote or network exception occurs 564 * @deprecated As of release 2.0.0. 565 * (<a href="https://issues.apache.org/jira/browse/HBASE-1989">HBASE-1989</a>). 566 * This will be removed in HBase 3.0.0. 567 * Use {@link #modifyColumnFamily(TableName, HColumnDescriptor)}. 568 */ 569 @Deprecated 570 void modifyColumn(final TableName tableName, final HColumnDescriptor columnFamily) 571 throws IOException; 572 573 /** 574 * Modify an existing column family on a table. Asynchronous operation. 575 * 576 * @param tableName name of table 577 * @param columnFamily new column family descriptor to use 578 * @throws IOException if a remote or network exception occurs 579 * @return the result of the async modify column family. You can use Future.get(long, TimeUnit) to 580 * wait on the operation to complete. 581 */ 582 Future<Void> modifyColumnFamily(final TableName tableName, final HColumnDescriptor columnFamily) 583 throws IOException; 584 585 586 /** 587 * Close a region. For expert-admins. Runs close on the regionserver. The master will not be 588 * informed of the close. 589 * 590 * @param regionname region name to close 591 * @param serverName If supplied, we'll use this location rather than the one currently in 592 * <code>hbase:meta</code> 593 * @throws IOException if a remote or network exception occurs 594 */ 595 void closeRegion(final String regionname, final String serverName) throws IOException; 596 597 /** 598 * Close a region. For expert-admins Runs close on the regionserver. The master will not be 599 * informed of the close. 600 * 601 * @param regionname region name to close 602 * @param serverName The servername of the regionserver. If passed null we will use servername 603 * found in the hbase:meta table. A server name is made of host, port and startcode. Here is an 604 * example: <code> host187.example.com,60020,1289493121758</code> 605 * @throws IOException if a remote or network exception occurs 606 */ 607 void closeRegion(final byte[] regionname, final String serverName) throws IOException; 608 609 /** 610 * For expert-admins. Runs close on the regionserver. Closes a region based on the encoded region 611 * name. The region server name is mandatory. If the servername is provided then based on the 612 * online regions in the specified regionserver the specified region will be closed. The master 613 * will not be informed of the close. Note that the regionname is the encoded regionname. 614 * 615 * @param encodedRegionName The encoded region name; i.e. the hash that makes up the region name 616 * suffix: e.g. if regionname is 617 * <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>, 618 * then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>. 619 * @param serverName The servername of the regionserver. A server name is made of host, port and 620 * startcode. This is mandatory. Here is an example: 621 * <code> host187.example.com,60020,1289493121758</code> 622 * @return true if the region was closed, false if not. 623 * @throws IOException if a remote or network exception occurs 624 */ 625 boolean closeRegionWithEncodedRegionName(final String encodedRegionName, final String serverName) 626 throws IOException; 627 628 /** 629 * Close a region. For expert-admins Runs close on the regionserver. The master will not be 630 * informed of the close. 631 * 632 * @param sn 633 * @param hri 634 * @throws IOException 635 */ 636 void closeRegion(final ServerName sn, final HRegionInfo hri) throws IOException; 637 638 /** 639 * Get all the online regions on a region server. 640 */ 641 List<HRegionInfo> getOnlineRegions(final ServerName sn) throws IOException; 642 643 /** 644 * Flush a table. Synchronous operation. 645 * 646 * @param tableName table to flush 647 * @throws IOException if a remote or network exception occurs 648 */ 649 void flush(final TableName tableName) throws IOException; 650 651 /** 652 * Flush an individual region. Synchronous operation. 653 * 654 * @param regionName region to flush 655 * @throws IOException if a remote or network exception occurs 656 */ 657 void flushRegion(final byte[] regionName) throws IOException; 658 659 /** 660 * Compact a table. Asynchronous operation. 661 * 662 * @param tableName table to compact 663 * @throws IOException if a remote or network exception occurs 664 */ 665 void compact(final TableName tableName) throws IOException; 666 667 /** 668 * Compact an individual region. Asynchronous operation. 669 * 670 * @param regionName region to compact 671 * @throws IOException if a remote or network exception occurs 672 */ 673 void compactRegion(final byte[] regionName) throws IOException; 674 675 /** 676 * Compact a column family within a table. Asynchronous operation. 677 * 678 * @param tableName table to compact 679 * @param columnFamily column family within a table 680 * @throws IOException if a remote or network exception occurs 681 */ 682 void compact(final TableName tableName, final byte[] columnFamily) 683 throws IOException; 684 685 /** 686 * Compact a column family within a region. Asynchronous operation. 687 * 688 * @param regionName region to compact 689 * @param columnFamily column family within a region 690 * @throws IOException if a remote or network exception occurs 691 */ 692 void compactRegion(final byte[] regionName, final byte[] columnFamily) 693 throws IOException; 694 695 /** 696 * Major compact a table. Asynchronous operation. 697 * 698 * @param tableName table to major compact 699 * @throws IOException if a remote or network exception occurs 700 */ 701 void majorCompact(TableName tableName) throws IOException; 702 703 /** 704 * Major compact a table or an individual region. Asynchronous operation. 705 * 706 * @param regionName region to major compact 707 * @throws IOException if a remote or network exception occurs 708 */ 709 void majorCompactRegion(final byte[] regionName) throws IOException; 710 711 /** 712 * Major compact a column family within a table. Asynchronous operation. 713 * 714 * @param tableName table to major compact 715 * @param columnFamily column family within a table 716 * @throws IOException if a remote or network exception occurs 717 */ 718 void majorCompact(TableName tableName, final byte[] columnFamily) 719 throws IOException; 720 721 /** 722 * Major compact a column family within region. Asynchronous operation. 723 * 724 * @param regionName egion to major compact 725 * @param columnFamily column family within a region 726 * @throws IOException if a remote or network exception occurs 727 */ 728 void majorCompactRegion(final byte[] regionName, final byte[] columnFamily) 729 throws IOException; 730 731 /** 732 * Compact all regions on the region server 733 * @param sn the region server name 734 * @param major if it's major compaction 735 * @throws IOException 736 * @throws InterruptedException 737 */ 738 public void compactRegionServer(final ServerName sn, boolean major) 739 throws IOException, InterruptedException; 740 741 /** 742 * Move the region <code>r</code> to <code>dest</code>. 743 * 744 * @param encodedRegionName The encoded region name; i.e. the hash that makes up the region name 745 * suffix: e.g. if regionname is 746 * <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>, 747 * then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>. 748 * @param destServerName The servername of the destination regionserver. If passed the empty byte 749 * array we'll assign to a random server. A server name is made of host, port and startcode. 750 * Here is an example: <code> host187.example.com,60020,1289493121758</code> 751 * @throws IOException if we can't find a region named 752 * <code>encodedRegionName</code> 753 */ 754 void move(final byte[] encodedRegionName, final byte[] destServerName) 755 throws IOException; 756 757 /** 758 * @param regionName Region name to assign. 759 */ 760 void assign(final byte[] regionName) 761 throws IOException; 762 763 /** 764 * Unassign a region from current hosting regionserver. Region will then be assigned to a 765 * regionserver chosen at random. Region could be reassigned back to the same server. Use {@link 766 * #move(byte[], byte[])} if you want to control the region movement. 767 * 768 * @param regionName Region to unassign. Will clear any existing RegionPlan if one found. 769 * @param force If true, force unassign (Will remove region from regions-in-transition too if 770 * present. If results in double assignment use hbck -fix to resolve. To be used by experts). 771 */ 772 void unassign(final byte[] regionName, final boolean force) 773 throws IOException; 774 775 /** 776 * Offline specified region from master's in-memory state. It will not attempt to reassign the 777 * region as in unassign. This API can be used when a region not served by any region server and 778 * still online as per Master's in memory state. If this API is incorrectly used on active region 779 * then master will loose track of that region. This is a special method that should be used by 780 * experts or hbck. 781 * 782 * @param regionName Region to offline. 783 * @throws IOException 784 */ 785 void offline(final byte[] regionName) throws IOException; 786 787 /** 788 * Turn the load balancer on or off. 789 * 790 * @param synchronous If true, it waits until current balance() call, if outstanding, to return. 791 * @return Previous balancer value 792 */ 793 boolean setBalancerRunning(final boolean on, final boolean synchronous) 794 throws IOException; 795 796 /** 797 * Invoke the balancer. Will run the balancer and if regions to move, it will go ahead and do the 798 * reassignments. Can NOT run for various reasons. Check logs. 799 * 800 * @return True if balancer ran, false otherwise. 801 */ 802 boolean balancer() throws IOException; 803 804 /** 805 * Invoke the balancer. Will run the balancer and if regions to move, it will 806 * go ahead and do the reassignments. If there is region in transition, force parameter of true 807 * would still run balancer. Can *not* run for other reasons. Check 808 * logs. 809 * @param force whether we should force balance even if there is region in transition 810 * @return True if balancer ran, false otherwise. 811 */ 812 boolean balancer(boolean force) throws IOException; 813 814 /** 815 * Query the current state of the balancer 816 * 817 * @return true if the balancer is enabled, false otherwise. 818 */ 819 boolean isBalancerEnabled() throws IOException; 820 821 /** 822 * Invoke region normalizer. Can NOT run for various reasons. Check logs. 823 * 824 * @return True if region normalizer ran, false otherwise. 825 */ 826 boolean normalize() throws IOException; 827 828 /** 829 * Query the current state of the region normalizer 830 * 831 * @return true if region normalizer is enabled, false otherwise. 832 */ 833 boolean isNormalizerEnabled() throws IOException; 834 835 /** 836 * Turn region normalizer on or off. 837 * 838 * @return Previous normalizer value 839 */ 840 boolean setNormalizerRunning(final boolean on) 841 throws IOException; 842 843 /** 844 * Enable/Disable the catalog janitor 845 * 846 * @param enable if true enables the catalog janitor 847 * @return the previous state 848 */ 849 boolean enableCatalogJanitor(boolean enable) throws IOException; 850 851 /** 852 * Ask for a scan of the catalog table 853 * 854 * @return the number of entries cleaned 855 */ 856 int runCatalogScan() throws IOException; 857 858 /** 859 * Query on the catalog janitor state (Enabled/Disabled?) 860 * 861 */ 862 boolean isCatalogJanitorEnabled() throws IOException; 863 864 /** 865 * Merge two regions. Asynchronous operation. 866 * 867 * @param encodedNameOfRegionA encoded name of region a 868 * @param encodedNameOfRegionB encoded name of region b 869 * @param forcible true if do a compulsory merge, otherwise we will only merge two adjacent 870 * regions 871 * @throws IOException 872 */ 873 void mergeRegions(final byte[] encodedNameOfRegionA, final byte[] encodedNameOfRegionB, 874 final boolean forcible) throws IOException; 875 876 /** 877 * Split a table. Asynchronous operation. 878 * 879 * @param tableName table to split 880 * @throws IOException if a remote or network exception occurs 881 */ 882 void split(final TableName tableName) throws IOException; 883 884 /** 885 * Split an individual region. Asynchronous operation. 886 * 887 * @param regionName region to split 888 * @throws IOException if a remote or network exception occurs 889 */ 890 void splitRegion(final byte[] regionName) throws IOException; 891 892 /** 893 * Split a table. Asynchronous operation. 894 * 895 * @param tableName table to split 896 * @param splitPoint the explicit position to split on 897 * @throws IOException if a remote or network exception occurs 898 */ 899 void split(final TableName tableName, final byte[] splitPoint) 900 throws IOException; 901 902 /** 903 * Split an individual region. Asynchronous operation. 904 * 905 * @param regionName region to split 906 * @param splitPoint the explicit position to split on 907 * @throws IOException if a remote or network exception occurs 908 */ 909 void splitRegion(final byte[] regionName, final byte[] splitPoint) 910 throws IOException; 911 912 /** 913 * Modify an existing table, more IRB friendly version. Asynchronous operation. This means that 914 * it may be a while before your schema change is updated across all of the table. 915 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 916 * It may throw ExecutionException if there was an error while executing the operation 917 * or TimeoutException in case the wait timeout was not long enough to allow the 918 * operation to complete. 919 * 920 * @param tableName name of table. 921 * @param htd modified description of the table 922 * @throws IOException if a remote or network exception occurs 923 * @return the result of the async modify. You can use Future.get(long, TimeUnit) to wait on the 924 * operation to complete 925 */ 926 Future<Void> modifyTable(final TableName tableName, final HTableDescriptor htd) 927 throws IOException; 928 929 /** 930 * Shuts down the HBase cluster 931 * 932 * @throws IOException if a remote or network exception occurs 933 */ 934 void shutdown() throws IOException; 935 936 /** 937 * Shuts down the current HBase master only. Does not shutdown the cluster. 938 * 939 * @throws IOException if a remote or network exception occurs 940 * @see #shutdown() 941 */ 942 void stopMaster() throws IOException; 943 944 /** 945 * Stop the designated regionserver 946 * 947 * @param hostnamePort Hostname and port delimited by a <code>:</code> as in 948 * <code>example.org:1234</code> 949 * @throws IOException if a remote or network exception occurs 950 */ 951 void stopRegionServer(final String hostnamePort) throws IOException; 952 953 /** 954 * @return cluster status 955 * @throws IOException if a remote or network exception occurs 956 */ 957 ClusterStatus getClusterStatus() throws IOException; 958 959 /** 960 * @return Configuration used by the instance. 961 */ 962 Configuration getConfiguration(); 963 964 /** 965 * Create a new namespace 966 * 967 * @param descriptor descriptor which describes the new namespace 968 * @throws IOException 969 */ 970 void createNamespace(final NamespaceDescriptor descriptor) 971 throws IOException; 972 973 /** 974 * Modify an existing namespace 975 * 976 * @param descriptor descriptor which describes the new namespace 977 * @throws IOException 978 */ 979 void modifyNamespace(final NamespaceDescriptor descriptor) 980 throws IOException; 981 982 /** 983 * Delete an existing namespace. Only empty namespaces (no tables) can be removed. 984 * 985 * @param name namespace name 986 * @throws IOException 987 */ 988 void deleteNamespace(final String name) throws IOException; 989 990 /** 991 * Get a namespace descriptor by name 992 * 993 * @param name name of namespace descriptor 994 * @return A descriptor 995 * @throws IOException 996 */ 997 NamespaceDescriptor getNamespaceDescriptor(final String name) 998 throws IOException; 999 1000 /** 1001 * List available namespace descriptors 1002 * 1003 * @return List of descriptors 1004 * @throws IOException 1005 */ 1006 NamespaceDescriptor[] listNamespaceDescriptors() 1007 throws IOException; 1008 1009 /** 1010 * Get list of table descriptors by namespace 1011 * 1012 * @param name namespace name 1013 * @return A descriptor 1014 * @throws IOException 1015 */ 1016 HTableDescriptor[] listTableDescriptorsByNamespace(final String name) 1017 throws IOException; 1018 1019 /** 1020 * Get list of table names by namespace 1021 * 1022 * @param name namespace name 1023 * @return The list of table names in the namespace 1024 * @throws IOException 1025 */ 1026 TableName[] listTableNamesByNamespace(final String name) 1027 throws IOException; 1028 1029 /** 1030 * Get the regions of a given table. 1031 * 1032 * @param tableName the name of the table 1033 * @return List of {@link HRegionInfo}. 1034 * @throws IOException 1035 */ 1036 List<HRegionInfo> getTableRegions(final TableName tableName) 1037 throws IOException; 1038 1039 @Override 1040 void close() throws IOException; 1041 1042 /** 1043 * Get tableDescriptors 1044 * 1045 * @param tableNames List of table names 1046 * @return HTD[] the tableDescriptor 1047 * @throws IOException if a remote or network exception occurs 1048 */ 1049 HTableDescriptor[] getTableDescriptorsByTableName(List<TableName> tableNames) 1050 throws IOException; 1051 1052 /** 1053 * Get tableDescriptors 1054 * 1055 * @param names List of table names 1056 * @return HTD[] the tableDescriptor 1057 * @throws IOException if a remote or network exception occurs 1058 */ 1059 HTableDescriptor[] getTableDescriptors(List<String> names) 1060 throws IOException; 1061 1062 /** 1063 * abort a procedure 1064 * @param procId ID of the procedure to abort 1065 * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted? 1066 * @return true if aborted, false if procedure already completed or does not exist 1067 * @throws IOException 1068 */ 1069 boolean abortProcedure( 1070 final long procId, 1071 final boolean mayInterruptIfRunning) throws IOException; 1072 1073 /** 1074 * Abort a procedure but does not block and wait for it be completely removed. 1075 * You can use Future.get(long, TimeUnit) to wait on the operation to complete. 1076 * It may throw ExecutionException if there was an error while executing the operation 1077 * or TimeoutException in case the wait timeout was not long enough to allow the 1078 * operation to complete. 1079 * 1080 * @param procId ID of the procedure to abort 1081 * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted? 1082 * @return true if aborted, false if procedure already completed or does not exist 1083 * @throws IOException 1084 */ 1085 Future<Boolean> abortProcedureAsync( 1086 final long procId, 1087 final boolean mayInterruptIfRunning) throws IOException; 1088 1089 /** 1090 * List procedures 1091 * @return procedure list 1092 * @throws IOException 1093 */ 1094 ProcedureInfo[] listProcedures() 1095 throws IOException; 1096 1097 /** 1098 * Roll the log writer. I.e. for filesystem based write ahead logs, start writing to a new file. 1099 * 1100 * Note that the actual rolling of the log writer is asynchronous and may not be complete when 1101 * this method returns. As a side effect of this call, the named region server may schedule 1102 * store flushes at the request of the wal. 1103 * 1104 * @param serverName The servername of the regionserver. 1105 * @throws IOException if a remote or network exception occurs 1106 * @throws org.apache.hadoop.hbase.regionserver.wal.FailedLogCloseException 1107 */ 1108 void rollWALWriter(ServerName serverName) throws IOException, FailedLogCloseException; 1109 1110 /** 1111 * Helper delegage to getClusterStatus().getMasterCoprocessors(). 1112 * @return an array of master coprocessors 1113 * @see org.apache.hadoop.hbase.ClusterStatus#getMasterCoprocessors() 1114 */ 1115 String[] getMasterCoprocessors() throws IOException; 1116 1117 /** 1118 * Get the current compaction state of a table. It could be in a major compaction, a minor 1119 * compaction, both, or none. 1120 * 1121 * @param tableName table to examine 1122 * @return the current compaction state 1123 * @throws IOException if a remote or network exception occurs 1124 */ 1125 AdminProtos.GetRegionInfoResponse.CompactionState getCompactionState(final TableName tableName) 1126 throws IOException; 1127 1128 /** 1129 * Get the current compaction state of region. It could be in a major compaction, a minor 1130 * compaction, both, or none. 1131 * 1132 * @param regionName region to examine 1133 * @return the current compaction state 1134 * @throws IOException if a remote or network exception occurs 1135 */ 1136 AdminProtos.GetRegionInfoResponse.CompactionState getCompactionStateForRegion( 1137 final byte[] regionName) throws IOException; 1138 1139 /** 1140 * Get the timestamp of the last major compaction for the passed table 1141 * 1142 * The timestamp of the oldest HFile resulting from a major compaction of that table, 1143 * or 0 if no such HFile could be found. 1144 * 1145 * @param tableName table to examine 1146 * @return the last major compaction timestamp or 0 1147 * @throws IOException if a remote or network exception occurs 1148 */ 1149 long getLastMajorCompactionTimestamp(final TableName tableName) 1150 throws IOException; 1151 1152 /** 1153 * Get the timestamp of the last major compaction for the passed region. 1154 * 1155 * The timestamp of the oldest HFile resulting from a major compaction of that region, 1156 * or 0 if no such HFile could be found. 1157 * 1158 * @param regionName region to examine 1159 * @return the last major compaction timestamp or 0 1160 * @throws IOException if a remote or network exception occurs 1161 */ 1162 long getLastMajorCompactionTimestampForRegion(final byte[] regionName) 1163 throws IOException; 1164 1165 /** 1166 * Take a snapshot for the given table. If the table is enabled, a FLUSH-type snapshot will be 1167 * taken. If the table is disabled, an offline snapshot is taken. Snapshots are considered unique 1168 * based on <b>the name of the snapshot</b>. Attempts to take a snapshot with the same name (even 1169 * a different type or with different parameters) will fail with a {@link 1170 * org.apache.hadoop.hbase.snapshot.SnapshotCreationException} indicating the duplicate naming. 1171 * Snapshot names follow the same naming constraints as tables in HBase. See {@link 1172 * org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}. 1173 * 1174 * @param snapshotName name of the snapshot to be created 1175 * @param tableName name of the table for which snapshot is created 1176 * @throws IOException if a remote or network exception occurs 1177 * @throws org.apache.hadoop.hbase.snapshot.SnapshotCreationException if snapshot creation failed 1178 * @throws IllegalArgumentException if the snapshot request is formatted incorrectly 1179 */ 1180 void snapshot(final String snapshotName, final TableName tableName) 1181 throws IOException, SnapshotCreationException, IllegalArgumentException; 1182 1183 /** 1184 * public void snapshot(final String snapshotName, Create a timestamp consistent snapshot for the 1185 * given table. final byte[] tableName) throws IOException, Snapshots are considered unique based 1186 * on <b>the name of the snapshot</b>. Attempts to take a snapshot with the same name (even a 1187 * different type or with different parameters) will fail with a {@link SnapshotCreationException} 1188 * indicating the duplicate naming. Snapshot names follow the same naming constraints as tables in 1189 * HBase. 1190 * 1191 * @param snapshotName name of the snapshot to be created 1192 * @param tableName name of the table for which snapshot is created 1193 * @throws IOException if a remote or network exception occurs 1194 * @throws SnapshotCreationException if snapshot creation failed 1195 * @throws IllegalArgumentException if the snapshot request is formatted incorrectly 1196 */ 1197 void snapshot(final byte[] snapshotName, final TableName tableName) 1198 throws IOException, SnapshotCreationException, IllegalArgumentException; 1199 1200 /** 1201 * Create typed snapshot of the table. Snapshots are considered unique based on <b>the name of the 1202 * snapshot</b>. Attempts to take a snapshot with the same name (even a different type or with 1203 * different parameters) will fail with a {@link SnapshotCreationException} indicating the 1204 * duplicate naming. Snapshot names follow the same naming constraints as tables in HBase. See 1205 * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}. 1206 * 1207 * @param snapshotName name to give the snapshot on the filesystem. Must be unique from all other 1208 * snapshots stored on the cluster 1209 * @param tableName name of the table to snapshot 1210 * @param type type of snapshot to take 1211 * @throws IOException we fail to reach the master 1212 * @throws SnapshotCreationException if snapshot creation failed 1213 * @throws IllegalArgumentException if the snapshot request is formatted incorrectly 1214 */ 1215 void snapshot(final String snapshotName, 1216 final TableName tableName, 1217 HBaseProtos.SnapshotDescription.Type type) throws IOException, SnapshotCreationException, 1218 IllegalArgumentException; 1219 1220 /** 1221 * Take a snapshot and wait for the server to complete that snapshot (blocking). Only a single 1222 * snapshot should be taken at a time for an instance of HBase, or results may be undefined (you 1223 * can tell multiple HBase clusters to snapshot at the same time, but only one at a time for a 1224 * single cluster). Snapshots are considered unique based on <b>the name of the snapshot</b>. 1225 * Attempts to take a snapshot with the same name (even a different type or with different 1226 * parameters) will fail with a {@link SnapshotCreationException} indicating the duplicate naming. 1227 * Snapshot names follow the same naming constraints as tables in HBase. See {@link 1228 * org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}. You should probably 1229 * use {@link #snapshot(String, org.apache.hadoop.hbase.TableName)} or 1230 * {@link #snapshot(byte[], org.apache.hadoop.hbase.TableName)} unless you are sure about the type 1231 * of snapshot that you want to take. 1232 * 1233 * @param snapshot snapshot to take 1234 * @throws IOException or we lose contact with the master. 1235 * @throws SnapshotCreationException if snapshot failed to be taken 1236 * @throws IllegalArgumentException if the snapshot request is formatted incorrectly 1237 */ 1238 void snapshot(HBaseProtos.SnapshotDescription snapshot) 1239 throws IOException, SnapshotCreationException, IllegalArgumentException; 1240 1241 /** 1242 * Take a snapshot without waiting for the server to complete that snapshot (asynchronous) Only a 1243 * single snapshot should be taken at a time, or results may be undefined. 1244 * 1245 * @param snapshot snapshot to take 1246 * @return response from the server indicating the max time to wait for the snapshot 1247 * @throws IOException if the snapshot did not succeed or we lose contact with the master. 1248 * @throws SnapshotCreationException if snapshot creation failed 1249 * @throws IllegalArgumentException if the snapshot request is formatted incorrectly 1250 */ 1251 MasterProtos.SnapshotResponse takeSnapshotAsync(HBaseProtos.SnapshotDescription snapshot) 1252 throws IOException, SnapshotCreationException; 1253 1254 /** 1255 * Check the current state of the passed snapshot. There are three possible states: <ol> 1256 * <li>running - returns <tt>false</tt></li> <li>finished - returns <tt>true</tt></li> 1257 * <li>finished with error - throws the exception that caused the snapshot to fail</li> </ol> The 1258 * cluster only knows about the most recent snapshot. Therefore, if another snapshot has been 1259 * run/started since the snapshot your are checking, you will recieve an {@link 1260 * org.apache.hadoop.hbase.snapshot.UnknownSnapshotException}. 1261 * 1262 * @param snapshot description of the snapshot to check 1263 * @return <tt>true</tt> if the snapshot is completed, <tt>false</tt> if the snapshot is still 1264 * running 1265 * @throws IOException if we have a network issue 1266 * @throws org.apache.hadoop.hbase.snapshot.HBaseSnapshotException if the snapshot failed 1267 * @throws org.apache.hadoop.hbase.snapshot.UnknownSnapshotException if the requested snapshot is 1268 * unknown 1269 */ 1270 boolean isSnapshotFinished(final HBaseProtos.SnapshotDescription snapshot) 1271 throws IOException, HBaseSnapshotException, UnknownSnapshotException; 1272 1273 /** 1274 * Restore the specified snapshot on the original table. (The table must be disabled) If the 1275 * "hbase.snapshot.restore.take.failsafe.snapshot" configuration property is set to true, a 1276 * snapshot of the current table is taken before executing the restore operation. In case of 1277 * restore failure, the failsafe snapshot will be restored. If the restore completes without 1278 * problem the failsafe snapshot is deleted. 1279 * 1280 * @param snapshotName name of the snapshot to restore 1281 * @throws IOException if a remote or network exception occurs 1282 * @throws org.apache.hadoop.hbase.snapshot.RestoreSnapshotException if snapshot failed to be 1283 * restored 1284 * @throws IllegalArgumentException if the restore request is formatted incorrectly 1285 */ 1286 void restoreSnapshot(final byte[] snapshotName) throws IOException, RestoreSnapshotException; 1287 1288 /** 1289 * Restore the specified snapshot on the original table. (The table must be disabled) If the 1290 * "hbase.snapshot.restore.take.failsafe.snapshot" configuration property is set to true, a 1291 * snapshot of the current table is taken before executing the restore operation. In case of 1292 * restore failure, the failsafe snapshot will be restored. If the restore completes without 1293 * problem the failsafe snapshot is deleted. 1294 * 1295 * @param snapshotName name of the snapshot to restore 1296 * @throws IOException if a remote or network exception occurs 1297 * @throws RestoreSnapshotException if snapshot failed to be restored 1298 * @throws IllegalArgumentException if the restore request is formatted incorrectly 1299 */ 1300 void restoreSnapshot(final String snapshotName) throws IOException, RestoreSnapshotException; 1301 1302 /** 1303 * Restore the specified snapshot on the original table. (The table must be disabled) If 1304 * 'takeFailSafeSnapshot' is set to true, a snapshot of the current table is taken before 1305 * executing the restore operation. In case of restore failure, the failsafe snapshot will be 1306 * restored. If the restore completes without problem the failsafe snapshot is deleted. The 1307 * failsafe snapshot name is configurable by using the property 1308 * "hbase.snapshot.restore.failsafe.name". 1309 * 1310 * @param snapshotName name of the snapshot to restore 1311 * @param takeFailSafeSnapshot true if the failsafe snapshot should be taken 1312 * @throws IOException if a remote or network exception occurs 1313 * @throws RestoreSnapshotException if snapshot failed to be restored 1314 * @throws IllegalArgumentException if the restore request is formatted incorrectly 1315 */ 1316 void restoreSnapshot(final byte[] snapshotName, final boolean takeFailSafeSnapshot) 1317 throws IOException, RestoreSnapshotException; 1318 1319 /** 1320 * Restore the specified snapshot on the original table. (The table must be disabled) If 1321 * 'takeFailSafeSnapshot' is set to true, a snapshot of the current table is taken before 1322 * executing the restore operation. In case of restore failure, the failsafe snapshot will be 1323 * restored. If the restore completes without problem the failsafe snapshot is deleted. The 1324 * failsafe snapshot name is configurable by using the property 1325 * "hbase.snapshot.restore.failsafe.name". 1326 * 1327 * @param snapshotName name of the snapshot to restore 1328 * @param takeFailSafeSnapshot true if the failsafe snapshot should be taken 1329 * @throws IOException if a remote or network exception occurs 1330 * @throws RestoreSnapshotException if snapshot failed to be restored 1331 * @throws IllegalArgumentException if the restore request is formatted incorrectly 1332 */ 1333 void restoreSnapshot(final String snapshotName, boolean takeFailSafeSnapshot) 1334 throws IOException, RestoreSnapshotException; 1335 1336 /** 1337 * Create a new table by cloning the snapshot content. 1338 * 1339 * @param snapshotName name of the snapshot to be cloned 1340 * @param tableName name of the table where the snapshot will be restored 1341 * @throws IOException if a remote or network exception occurs 1342 * @throws TableExistsException if table to be created already exists 1343 * @throws RestoreSnapshotException if snapshot failed to be cloned 1344 * @throws IllegalArgumentException if the specified table has not a valid name 1345 */ 1346 void cloneSnapshot(final byte[] snapshotName, final TableName tableName) 1347 throws IOException, TableExistsException, RestoreSnapshotException; 1348 1349 /** 1350 * Create a new table by cloning the snapshot content. 1351 * 1352 * @param snapshotName name of the snapshot to be cloned 1353 * @param tableName name of the table where the snapshot will be restored 1354 * @throws IOException if a remote or network exception occurs 1355 * @throws TableExistsException if table to be created already exists 1356 * @throws RestoreSnapshotException if snapshot failed to be cloned 1357 * @throws IllegalArgumentException if the specified table has not a valid name 1358 */ 1359 void cloneSnapshot(final String snapshotName, final TableName tableName) 1360 throws IOException, TableExistsException, RestoreSnapshotException; 1361 1362 /** 1363 * Execute a distributed procedure on a cluster. 1364 * 1365 * @param signature A distributed procedure is uniquely identified by its signature (default the 1366 * root ZK node name of the procedure). 1367 * @param instance The instance name of the procedure. For some procedures, this parameter is 1368 * optional. 1369 * @param props Property/Value pairs of properties passing to the procedure 1370 * @throws IOException 1371 */ 1372 void execProcedure(String signature, String instance, Map<String, String> props) 1373 throws IOException; 1374 1375 /** 1376 * Execute a distributed procedure on a cluster. 1377 * 1378 * @param signature A distributed procedure is uniquely identified by its signature (default the 1379 * root ZK node name of the procedure). 1380 * @param instance The instance name of the procedure. For some procedures, this parameter is 1381 * optional. 1382 * @param props Property/Value pairs of properties passing to the procedure 1383 * @return data returned after procedure execution. null if no return data. 1384 * @throws IOException 1385 */ 1386 byte[] execProcedureWithRet(String signature, String instance, Map<String, String> props) 1387 throws IOException; 1388 1389 /** 1390 * Check the current state of the specified procedure. There are three possible states: <ol> 1391 * <li>running - returns <tt>false</tt></li> <li>finished - returns <tt>true</tt></li> 1392 * <li>finished with error - throws the exception that caused the procedure to fail</li> </ol> 1393 * 1394 * @param signature The signature that uniquely identifies a procedure 1395 * @param instance The instance name of the procedure 1396 * @param props Property/Value pairs of properties passing to the procedure 1397 * @return true if the specified procedure is finished successfully, false if it is still running 1398 * @throws IOException if the specified procedure finished with error 1399 */ 1400 boolean isProcedureFinished(String signature, String instance, Map<String, String> props) 1401 throws IOException; 1402 1403 /** 1404 * List completed snapshots. 1405 * 1406 * @return a list of snapshot descriptors for completed snapshots 1407 * @throws IOException if a network error occurs 1408 */ 1409 List<HBaseProtos.SnapshotDescription> listSnapshots() throws IOException; 1410 1411 /** 1412 * List all the completed snapshots matching the given regular expression. 1413 * 1414 * @param regex The regular expression to match against 1415 * @return - returns a List of SnapshotDescription 1416 * @throws IOException if a remote or network exception occurs 1417 */ 1418 List<HBaseProtos.SnapshotDescription> listSnapshots(String regex) throws IOException; 1419 1420 /** 1421 * List all the completed snapshots matching the given pattern. 1422 * 1423 * @param pattern The compiled regular expression to match against 1424 * @return - returns a List of SnapshotDescription 1425 * @throws IOException if a remote or network exception occurs 1426 */ 1427 List<HBaseProtos.SnapshotDescription> listSnapshots(Pattern pattern) throws IOException; 1428 1429 /** 1430 * List all the completed snapshots matching the given table name regular expression and snapshot 1431 * name regular expression. 1432 * @param tableNameRegex The table name regular expression to match against 1433 * @param snapshotNameRegex The snapshot name regular expression to match against 1434 * @return - returns a List of completed SnapshotDescription 1435 * @throws IOException if a remote or network exception occurs 1436 */ 1437 List<HBaseProtos.SnapshotDescription> listTableSnapshots(String tableNameRegex, 1438 String snapshotNameRegex) throws IOException; 1439 1440 /** 1441 * List all the completed snapshots matching the given table name regular expression and snapshot 1442 * name regular expression. 1443 * @param tableNamePattern The compiled table name regular expression to match against 1444 * @param snapshotNamePattern The compiled snapshot name regular expression to match against 1445 * @return - returns a List of completed SnapshotDescription 1446 * @throws IOException if a remote or network exception occurs 1447 */ 1448 List<HBaseProtos.SnapshotDescription> listTableSnapshots(Pattern tableNamePattern, 1449 Pattern snapshotNamePattern) throws IOException; 1450 1451 /** 1452 * Delete an existing snapshot. 1453 * 1454 * @param snapshotName name of the snapshot 1455 * @throws IOException if a remote or network exception occurs 1456 */ 1457 void deleteSnapshot(final byte[] snapshotName) throws IOException; 1458 1459 /** 1460 * Delete an existing snapshot. 1461 * 1462 * @param snapshotName name of the snapshot 1463 * @throws IOException if a remote or network exception occurs 1464 */ 1465 void deleteSnapshot(final String snapshotName) throws IOException; 1466 1467 /** 1468 * Delete existing snapshots whose names match the pattern passed. 1469 * 1470 * @param regex The regular expression to match against 1471 * @throws IOException if a remote or network exception occurs 1472 */ 1473 void deleteSnapshots(final String regex) throws IOException; 1474 1475 /** 1476 * Delete existing snapshots whose names match the pattern passed. 1477 * 1478 * @param pattern pattern for names of the snapshot to match 1479 * @throws IOException if a remote or network exception occurs 1480 */ 1481 void deleteSnapshots(final Pattern pattern) throws IOException; 1482 1483 /** 1484 * Delete all existing snapshots matching the given table name regular expression and snapshot 1485 * name regular expression. 1486 * @param tableNameRegex The table name regular expression to match against 1487 * @param snapshotNameRegex The snapshot name regular expression to match against 1488 * @throws IOException if a remote or network exception occurs 1489 */ 1490 void deleteTableSnapshots(String tableNameRegex, String snapshotNameRegex) throws IOException; 1491 1492 /** 1493 * Delete all existing snapshots matching the given table name regular expression and snapshot 1494 * name regular expression. 1495 * @param tableNamePattern The compiled table name regular expression to match against 1496 * @param snapshotNamePattern The compiled snapshot name regular expression to match against 1497 * @throws IOException if a remote or network exception occurs 1498 */ 1499 void deleteTableSnapshots(Pattern tableNamePattern, Pattern snapshotNamePattern) 1500 throws IOException; 1501 1502 /** 1503 * Apply the new quota settings. 1504 * 1505 * @param quota the quota settings 1506 * @throws IOException if a remote or network exception occurs 1507 */ 1508 void setQuota(final QuotaSettings quota) throws IOException; 1509 1510 /** 1511 * Return a QuotaRetriever to list the quotas based on the filter. 1512 * 1513 * @param filter the quota settings filter 1514 * @return the quota retriever 1515 * @throws IOException if a remote or network exception occurs 1516 */ 1517 QuotaRetriever getQuotaRetriever(final QuotaFilter filter) throws IOException; 1518 1519 /** 1520 * Creates and returns a {@link com.google.protobuf.RpcChannel} instance connected to the active 1521 * master. <p> The obtained {@link com.google.protobuf.RpcChannel} instance can be used to access 1522 * a published coprocessor {@link com.google.protobuf.Service} using standard protobuf service 1523 * invocations: </p> <div style="background-color: #cccccc; padding: 2px"> 1524 * <blockquote><pre> 1525 * CoprocessorRpcChannel channel = myAdmin.coprocessorService(); 1526 * MyService.BlockingInterface service = MyService.newBlockingStub(channel); 1527 * MyCallRequest request = MyCallRequest.newBuilder() 1528 * ... 1529 * .build(); 1530 * MyCallResponse response = service.myCall(null, request); 1531 * </pre></blockquote></div> 1532 * 1533 * @return A MasterCoprocessorRpcChannel instance 1534 */ 1535 CoprocessorRpcChannel coprocessorService(); 1536 1537 1538 /** 1539 * Creates and returns a {@link com.google.protobuf.RpcChannel} instance 1540 * connected to the passed region server. 1541 * 1542 * <p> 1543 * The obtained {@link com.google.protobuf.RpcChannel} instance can be used to access a published 1544 * coprocessor {@link com.google.protobuf.Service} using standard protobuf service invocations: 1545 * </p> 1546 * 1547 * <div style="background-color: #cccccc; padding: 2px"> 1548 * <blockquote><pre> 1549 * CoprocessorRpcChannel channel = myAdmin.coprocessorService(serverName); 1550 * MyService.BlockingInterface service = MyService.newBlockingStub(channel); 1551 * MyCallRequest request = MyCallRequest.newBuilder() 1552 * ... 1553 * .build(); 1554 * MyCallResponse response = service.myCall(null, request); 1555 * </pre></blockquote></div> 1556 * 1557 * @param sn the server name to which the endpoint call is made 1558 * @return A RegionServerCoprocessorRpcChannel instance 1559 */ 1560 CoprocessorRpcChannel coprocessorService(ServerName sn); 1561 1562 1563 /** 1564 * Update the configuration and trigger an online config change 1565 * on the regionserver 1566 * @param server : The server whose config needs to be updated. 1567 * @throws IOException 1568 */ 1569 void updateConfiguration(ServerName server) throws IOException; 1570 1571 1572 /** 1573 * Update the configuration and trigger an online config change 1574 * on all the regionservers 1575 * @throws IOException 1576 */ 1577 void updateConfiguration() throws IOException; 1578 1579 /** 1580 * Get the info port of the current master if one is available. 1581 * @return master info port 1582 * @throws IOException 1583 */ 1584 public int getMasterInfoPort() throws IOException; 1585 1586 /** 1587 * Compact a table. Asynchronous operation. 1588 * 1589 * @param tableName table to compact 1590 * @param compactType {@link org.apache.hadoop.hbase.client.Admin.CompactType} 1591 * @throws IOException 1592 * @throws InterruptedException 1593 */ 1594 void compact(final TableName tableName, CompactType compactType) 1595 throws IOException, InterruptedException; 1596 1597 /** 1598 * Compact a column family within a table. Asynchronous operation. 1599 * 1600 * @param tableName table to compact 1601 * @param columnFamily column family within a table 1602 * @param compactType {@link org.apache.hadoop.hbase.client.Admin.CompactType} 1603 * @throws IOException if not a mob column family or if a remote or network exception occurs 1604 * @throws InterruptedException 1605 */ 1606 void compact(final TableName tableName, final byte[] columnFamily, CompactType compactType) 1607 throws IOException, InterruptedException; 1608 1609 /** 1610 * Major compact a table. Asynchronous operation. 1611 * 1612 * @param tableName table to compact 1613 * @param compactType {@link org.apache.hadoop.hbase.client.Admin.CompactType} 1614 * @throws IOException 1615 * @throws InterruptedException 1616 */ 1617 void majorCompact(final TableName tableName, CompactType compactType) 1618 throws IOException, InterruptedException; 1619 1620 /** 1621 * Major compact a column family within a table. Asynchronous operation. 1622 * 1623 * @param tableName table to compact 1624 * @param columnFamily column family within a table 1625 * @param compactType {@link org.apache.hadoop.hbase.client.Admin.CompactType} 1626 * @throws IOException if not a mob column family or if a remote or network exception occurs 1627 * @throws InterruptedException 1628 */ 1629 void majorCompact(final TableName tableName, final byte[] columnFamily, CompactType compactType) 1630 throws IOException, InterruptedException; 1631 1632 /** 1633 * Get the current compaction state of a table. It could be in a compaction, or none. 1634 * 1635 * @param tableName table to examine 1636 * @param compactType {@link org.apache.hadoop.hbase.client.Admin.CompactType} 1637 * @return the current compaction state 1638 * @throws IOException if a remote or network exception occurs 1639 */ 1640 AdminProtos.GetRegionInfoResponse.CompactionState getCompactionState(final TableName tableName, 1641 CompactType compactType) throws IOException; 1642 1643 /** 1644 * Return the set of supported security capabilities. 1645 * @throws IOException 1646 * @throws UnsupportedOperationException 1647 */ 1648 List<SecurityCapability> getSecurityCapabilities() throws IOException; 1649 1650 /** 1651 * Currently, there are only two compact types: 1652 * {@code NORMAL} means do store files compaction; 1653 * {@code MOB} means do mob files compaction. 1654 * */ 1655 1656 @InterfaceAudience.Public 1657 @InterfaceStability.Unstable 1658 public enum CompactType { 1659 1660 NORMAL (0), 1661 MOB (1); 1662 1663 CompactType(int value) {} 1664 } 1665 }