001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.client;
019
020import static org.apache.hadoop.hbase.util.FutureUtils.get;
021
022import java.io.Closeable;
023import java.io.IOException;
024import java.util.Collection;
025import java.util.EnumSet;
026import java.util.List;
027import java.util.Map;
028import java.util.Set;
029import java.util.concurrent.Future;
030import java.util.concurrent.TimeUnit;
031import java.util.regex.Pattern;
032import org.apache.hadoop.conf.Configuration;
033import org.apache.hadoop.hbase.Abortable;
034import org.apache.hadoop.hbase.CacheEvictionStats;
035import org.apache.hadoop.hbase.ClusterMetrics;
036import org.apache.hadoop.hbase.ClusterMetrics.Option;
037import org.apache.hadoop.hbase.NamespaceDescriptor;
038import org.apache.hadoop.hbase.NamespaceNotFoundException;
039import org.apache.hadoop.hbase.RegionMetrics;
040import org.apache.hadoop.hbase.ServerName;
041import org.apache.hadoop.hbase.TableExistsException;
042import org.apache.hadoop.hbase.TableName;
043import org.apache.hadoop.hbase.TableNotFoundException;
044import org.apache.hadoop.hbase.client.replication.ReplicationPeerConfigUtil;
045import org.apache.hadoop.hbase.client.replication.TableCFs;
046import org.apache.hadoop.hbase.client.security.SecurityCapability;
047import org.apache.hadoop.hbase.ipc.CoprocessorRpcChannel;
048import org.apache.hadoop.hbase.quotas.QuotaFilter;
049import org.apache.hadoop.hbase.quotas.QuotaSettings;
050import org.apache.hadoop.hbase.quotas.SpaceQuotaSnapshotView;
051import org.apache.hadoop.hbase.regionserver.wal.FailedLogCloseException;
052import org.apache.hadoop.hbase.replication.ReplicationException;
053import org.apache.hadoop.hbase.replication.ReplicationPeerConfig;
054import org.apache.hadoop.hbase.replication.ReplicationPeerDescription;
055import org.apache.hadoop.hbase.replication.SyncReplicationState;
056import org.apache.hadoop.hbase.security.access.GetUserPermissionsRequest;
057import org.apache.hadoop.hbase.security.access.Permission;
058import org.apache.hadoop.hbase.security.access.UserPermission;
059import org.apache.hadoop.hbase.snapshot.HBaseSnapshotException;
060import org.apache.hadoop.hbase.snapshot.RestoreSnapshotException;
061import org.apache.hadoop.hbase.snapshot.SnapshotCreationException;
062import org.apache.hadoop.hbase.snapshot.UnknownSnapshotException;
063import org.apache.hadoop.hbase.util.Bytes;
064import org.apache.yetus.audience.InterfaceAudience;
065
066/**
067 * The administrative API for HBase. Obtain an instance from {@link Connection#getAdmin()} and
068 * call {@link #close()} when done.
069 * <p>Admin can be used to create, drop, list, enable and disable and otherwise modify tables,
070 * as well as perform other administrative operations.
071 *
072 * @see ConnectionFactory
073 * @see Connection
074 * @see Table
075 * @since 0.99.0
076 */
077@InterfaceAudience.Public
078public interface Admin extends Abortable, Closeable {
079
080  /**
081   * Return the operation timeout for a rpc call.
082   * @see #getSyncWaitTimeout()
083   */
084  int getOperationTimeout();
085
086  /**
087   * Return the blocking wait time for an asynchronous operation. Can be configured by
088   * {@code hbase.client.sync.wait.timeout.msec}.
089   * <p/>
090   * For several operations, such as createTable, deleteTable, etc, the rpc call will finish right
091   * after we schedule a procedure at master side, so the timeout will not be controlled by the
092   * above {@link #getOperationTimeout()}. And timeout value here tells you how much time we will
093   * wait until the procedure at master side is finished.
094   * <p/>
095   * In general, you can consider that the implementation for XXXX method is just a
096   * XXXXAsync().get(getSyncWaitTimeout(), TimeUnit.MILLISECONDS).
097   * @see #getOperationTimeout()
098   */
099  int getSyncWaitTimeout();
100
101  @Override
102  void abort(String why, Throwable e);
103
104  @Override
105  boolean isAborted();
106
107  /**
108   * @return Connection used by this object.
109   */
110  Connection getConnection();
111
112  /**
113   * @param tableName Table to check.
114   * @return <code>true</code> if table exists already.
115   * @throws IOException if a remote or network exception occurs
116   */
117  boolean tableExists(TableName tableName) throws IOException;
118
119  /**
120   * List all the userspace tables.
121   *
122   * @return a list of TableDescriptors
123   * @throws IOException if a remote or network exception occurs
124   */
125  List<TableDescriptor> listTableDescriptors() throws IOException;
126
127  /**
128   * List all userspace tables and whether or not include system tables.
129   *
130   * @return a list of TableDescriptors
131   * @throws IOException if a remote or network exception occurs
132   */
133  List<TableDescriptor> listTableDescriptors(boolean includeSysTables) throws IOException;
134
135  /**
136   * List all the userspace tables that match the given pattern.
137   *
138   * @param pattern The compiled regular expression to match against
139   * @return a list of TableDescriptors
140   * @throws IOException if a remote or network exception occurs
141   * @see #listTableDescriptors()
142   */
143  default List<TableDescriptor> listTableDescriptors(Pattern pattern) throws IOException {
144    return listTableDescriptors(pattern, false);
145  }
146
147  /**
148   * List all the tables matching the given pattern.
149   *
150   * @param pattern The compiled regular expression to match against
151   * @param includeSysTables <code>false</code> to match only against userspace tables
152   * @return a list of TableDescriptors
153   * @throws IOException if a remote or network exception occurs
154   * @see #listTableDescriptors()
155   */
156  List<TableDescriptor> listTableDescriptors(Pattern pattern, boolean includeSysTables)
157      throws IOException;
158
159  /**
160   * List all of the names of userspace tables.
161   *
162   * @return TableName[] table names
163   * @throws IOException if a remote or network exception occurs
164   */
165  TableName[] listTableNames() throws IOException;
166
167  /**
168   * List all of the names of userspace tables.
169   * @param pattern The regular expression to match against
170   * @return array of table names
171   * @throws IOException if a remote or network exception occurs
172   */
173  default TableName[] listTableNames(Pattern pattern) throws IOException {
174    return listTableNames(pattern, false);
175  }
176
177  /**
178   * List all of the names of userspace tables.
179   * @param pattern The regular expression to match against
180   * @param includeSysTables <code>false</code> 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(Pattern pattern, boolean includeSysTables)
185      throws IOException;
186
187  /**
188   * Get a table descriptor.
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  TableDescriptor getDescriptor(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  default void createTable(TableDescriptor desc) throws IOException {
209    get(createTableAsync(desc), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
210  }
211
212  /**
213   * Creates a new table with the specified number of regions.  The start key specified will become
214   * the end key of the first region of the table, and the end key specified will become the start
215   * key of the last region of the table (the first region has a null start key and the last region
216   * has a null end key). BigInteger math will be used to divide the key range specified into enough
217   * segments to make the required number of total regions. Synchronous operation.
218   *
219   * @param desc table descriptor for table
220   * @param startKey beginning of key range
221   * @param endKey end of key range
222   * @param numRegions the total number of regions to create
223   * @throws IOException if a remote or network exception occurs
224   * @throws IllegalArgumentException if the table name is reserved
225   * @throws org.apache.hadoop.hbase.MasterNotRunningException if master is not running
226   * @throws org.apache.hadoop.hbase.TableExistsException if table already exists (If concurrent
227   * threads, the table may have been created between test-for-existence and attempt-at-creation).
228   */
229  void createTable(TableDescriptor desc, byte[] startKey, byte[] endKey, int numRegions)
230      throws IOException;
231
232  /**
233   * Creates a new table with an initial set of empty regions defined by the specified split keys.
234   * The total number of regions created will be the number of split keys plus one. Synchronous
235   * operation. Note : Avoid passing empty split key.
236   *
237   * @param desc table descriptor for table
238   * @param splitKeys array of split keys for the initial regions of the table
239   * @throws IllegalArgumentException if the table name is reserved, if the split keys are repeated
240   * and if the split key has empty byte array.
241   * @throws org.apache.hadoop.hbase.MasterNotRunningException if master is not running
242   * @throws org.apache.hadoop.hbase.TableExistsException if table already exists (If concurrent
243   * threads, the table may have been created between test-for-existence and attempt-at-creation).
244   * @throws IOException if a remote or network exception occurs
245   */
246  default void createTable(TableDescriptor desc, byte[][] splitKeys) throws IOException {
247    get(createTableAsync(desc, splitKeys), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
248  }
249
250  /**
251   * Creates a new table but does not block and wait for it to come online. You can use
252   * Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
253   * ExecutionException if there was an error while executing the operation or TimeoutException in
254   * case the wait timeout was not long enough to allow the operation to complete.
255   * <p/>
256   * Throws IllegalArgumentException Bad table name, if the split keys are repeated and if the split
257   * key has empty byte array.
258   * @param desc table descriptor for table
259   * @throws IOException if a remote or network exception occurs
260   * @return the result of the async creation. You can use Future.get(long, TimeUnit) to wait on the
261   *         operation to complete.
262   */
263  Future<Void> createTableAsync(TableDescriptor desc) throws IOException;
264
265  /**
266   * Creates a new table but does not block and wait for it to come online.
267   * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
268   * It may throw ExecutionException if there was an error while executing the operation
269   * or TimeoutException in case the wait timeout was not long enough to allow the
270   * operation to complete.
271   * Throws IllegalArgumentException Bad table name, if the split keys
272   *    are repeated and if the split key has empty byte array.
273   *
274   * @param desc table descriptor for table
275   * @param splitKeys keys to check if the table has been created with all split keys
276   * @throws IOException if a remote or network exception occurs
277   * @return the result of the async creation. You can use Future.get(long, TimeUnit) to wait on the
278   *         operation to complete.
279   */
280  Future<Void> createTableAsync(TableDescriptor desc, byte[][] splitKeys) throws IOException;
281
282  /**
283   * Deletes a table. Synchronous operation.
284   * @param tableName name of table to delete
285   * @throws IOException if a remote or network exception occurs
286   */
287  default void deleteTable(TableName tableName) throws IOException {
288    get(deleteTableAsync(tableName), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
289  }
290
291  /**
292   * Deletes the table but does not block and wait for it to be completely removed.
293   * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
294   * It may throw ExecutionException if there was an error while executing the operation
295   * or TimeoutException in case the wait timeout was not long enough to allow the
296   * operation to complete.
297   *
298   * @param tableName name of table to delete
299   * @throws IOException if a remote or network exception occurs
300   * @return the result of the async delete. You can use Future.get(long, TimeUnit)
301   *    to wait on the operation to complete.
302   */
303  Future<Void> deleteTableAsync(TableName tableName) throws IOException;
304
305  /**
306   * Truncate a table. Synchronous operation.
307   * @param tableName name of table to truncate
308   * @param preserveSplits <code>true</code> if the splits should be preserved
309   * @throws IOException if a remote or network exception occurs
310   */
311  default void truncateTable(TableName tableName, boolean preserveSplits) throws IOException {
312    get(truncateTableAsync(tableName, preserveSplits), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
313  }
314
315  /**
316   * Truncate the table but does not block and wait for it to be completely enabled. You can use
317   * Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
318   * ExecutionException if there was an error while executing the operation or TimeoutException in
319   * case the wait timeout was not long enough to allow the operation to complete.
320   * @param tableName name of table to delete
321   * @param preserveSplits <code>true</code> if the splits should be preserved
322   * @throws IOException if a remote or network exception occurs
323   * @return the result of the async truncate. You can use Future.get(long, TimeUnit) to wait on the
324   *         operation to complete.
325   */
326  Future<Void> truncateTableAsync(TableName tableName, boolean preserveSplits)
327      throws IOException;
328
329  /**
330   * Enable a table. May timeout. Use {@link #enableTableAsync(org.apache.hadoop.hbase.TableName)}
331   * and {@link #isTableEnabled(org.apache.hadoop.hbase.TableName)} instead. The table has to be in
332   * disabled state for it to be enabled.
333   * @param tableName name of the table
334   * @throws IOException There could be couple types of
335   *           IOException TableNotFoundException means the table doesn't exist.
336   *           TableNotDisabledException means the table isn't in disabled state.
337   * @see #isTableEnabled(org.apache.hadoop.hbase.TableName)
338   * @see #disableTable(org.apache.hadoop.hbase.TableName)
339   * @see #enableTableAsync(org.apache.hadoop.hbase.TableName)
340   */
341  default void enableTable(TableName tableName) throws IOException {
342    get(enableTableAsync(tableName), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
343  }
344
345  /**
346   * Enable the table but does not block and wait for it to be completely enabled.
347   * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
348   * It may throw ExecutionException if there was an error while executing the operation
349   * or TimeoutException in case the wait timeout was not long enough to allow the
350   * operation to complete.
351   *
352   * @param tableName name of table to delete
353   * @throws IOException if a remote or network exception occurs
354   * @return the result of the async enable. You can use Future.get(long, TimeUnit)
355   *    to wait on the operation to complete.
356   */
357  Future<Void> enableTableAsync(TableName tableName) throws IOException;
358
359  /**
360   * Disable the table but does not block and wait for it to be completely disabled.
361   * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
362   * It may throw ExecutionException if there was an error while executing the operation
363   * or TimeoutException in case the wait timeout was not long enough to allow the
364   * operation to complete.
365   *
366   * @param tableName name of table to delete
367   * @throws IOException if a remote or network exception occurs
368   * @return the result of the async disable. You can use Future.get(long, TimeUnit)
369   *    to wait on the operation to complete.
370   */
371  Future<Void> disableTableAsync(TableName tableName) throws IOException;
372
373  /**
374   * Disable table and wait on completion. May timeout eventually. Use
375   * {@link #disableTableAsync(org.apache.hadoop.hbase.TableName)} and
376   * {@link #isTableDisabled(org.apache.hadoop.hbase.TableName)} instead. The table has to be in
377   * enabled state for it to be disabled.
378   * @param tableName
379   * @throws IOException There could be couple types of IOException TableNotFoundException means the
380   *           table doesn't exist. TableNotEnabledException means the table isn't in enabled state.
381   */
382  default void disableTable(TableName tableName) throws IOException {
383    get(disableTableAsync(tableName), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
384  }
385
386  /**
387   * @param tableName name of table to check
388   * @return <code>true</code> if table is on-line
389   * @throws IOException if a remote or network exception occurs
390   */
391  boolean isTableEnabled(TableName tableName) throws IOException;
392
393  /**
394   * @param tableName name of table to check
395   * @return <code>true</code> if table is off-line
396   * @throws IOException if a remote or network exception occurs
397   */
398  boolean isTableDisabled(TableName tableName) throws IOException;
399
400  /**
401   * @param tableName name of table to check
402   * @return <code>true</code> if all regions of the table are available
403   * @throws IOException if a remote or network exception occurs
404   */
405  boolean isTableAvailable(TableName tableName) throws IOException;
406
407  /**
408   * Add a column family to an existing table. Synchronous operation. Use
409   * {@link #addColumnFamilyAsync(TableName, ColumnFamilyDescriptor)} instead because it returns a
410   * {@link Future} from which you can learn whether success or failure.
411   * @param tableName name of the table to add column family to
412   * @param columnFamily column family descriptor of column family to be added
413   * @throws IOException if a remote or network exception occurs
414   */
415  default void addColumnFamily(TableName tableName, ColumnFamilyDescriptor columnFamily)
416      throws IOException {
417    get(addColumnFamilyAsync(tableName, columnFamily), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
418  }
419
420  /**
421   * Add a column family to an existing table. Asynchronous operation.
422   * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
423   * It may throw ExecutionException if there was an error while executing the operation
424   * or TimeoutException in case the wait timeout was not long enough to allow the
425   * operation to complete.
426   *
427   * @param tableName name of the table to add column family to
428   * @param columnFamily column family descriptor of column family to be added
429   * @throws IOException if a remote or network exception occurs
430   * @return the result of the async add column family. You can use Future.get(long, TimeUnit) to
431   *         wait on the operation to complete.
432   */
433  Future<Void> addColumnFamilyAsync(TableName tableName, ColumnFamilyDescriptor columnFamily)
434      throws IOException;
435
436  /**
437   * Delete a column family from a table. Synchronous operation. Use
438   * {@link #deleteColumnFamily(TableName, byte[])} instead because it returns a {@link Future} from
439   * which you can learn whether success or failure.
440   * @param tableName name of table
441   * @param columnFamily name of column family to be deleted
442   * @throws IOException if a remote or network exception occurs
443   */
444  default void deleteColumnFamily(TableName tableName, byte[] columnFamily) throws IOException {
445    get(deleteColumnFamilyAsync(tableName, columnFamily), getSyncWaitTimeout(),
446      TimeUnit.MILLISECONDS);
447  }
448
449  /**
450   * Delete a column family from a table. Asynchronous operation.
451   * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
452   * It may throw ExecutionException if there was an error while executing the operation
453   * or TimeoutException in case the wait timeout was not long enough to allow the
454   * operation to complete.
455   *
456   * @param tableName name of table
457   * @param columnFamily name of column family to be deleted
458   * @throws IOException if a remote or network exception occurs
459   * @return the result of the async delete column family. You can use Future.get(long, TimeUnit) to
460   *         wait on the operation to complete.
461   */
462  Future<Void> deleteColumnFamilyAsync(TableName tableName, byte[] columnFamily)
463      throws IOException;
464
465  /**
466   * Modify an existing column family on a table. Synchronous operation. Use
467   * {@link #modifyColumnFamilyAsync(TableName, ColumnFamilyDescriptor)} instead because it returns
468   * a {@link Future} from which you can learn whether success or failure.
469   * @param tableName name of table
470   * @param columnFamily new column family descriptor to use
471   * @throws IOException if a remote or network exception occurs
472   */
473  default void modifyColumnFamily(TableName tableName, ColumnFamilyDescriptor columnFamily)
474      throws IOException {
475    get(modifyColumnFamilyAsync(tableName, columnFamily), getSyncWaitTimeout(),
476      TimeUnit.MILLISECONDS);
477  }
478
479  /**
480   * Modify an existing column family on a table. Asynchronous operation.
481   * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
482   * It may throw ExecutionException if there was an error while executing the operation
483   * or TimeoutException in case the wait timeout was not long enough to allow the
484   * operation to complete.
485   *
486   * @param tableName name of table
487   * @param columnFamily new column family descriptor to use
488   * @throws IOException if a remote or network exception occurs
489   * @return the result of the async modify column family. You can use Future.get(long, TimeUnit) to
490   *         wait on the operation to complete.
491   */
492  Future<Void> modifyColumnFamilyAsync(TableName tableName, ColumnFamilyDescriptor columnFamily)
493      throws IOException;
494
495  /**
496   * Get all the online regions on a region server.
497   *
498   * @return List of {@link RegionInfo}
499   * @throws IOException if a remote or network exception occurs
500   */
501  List<RegionInfo> getRegions(ServerName serverName) throws IOException;
502
503  /**
504   * Flush a table. Synchronous operation.
505   *
506   * @param tableName table to flush
507   * @throws IOException if a remote or network exception occurs
508   */
509  void flush(TableName tableName) throws IOException;
510
511  /**
512   * Flush an individual region. Synchronous operation.
513   *
514   * @param regionName region to flush
515   * @throws IOException if a remote or network exception occurs
516   */
517  void flushRegion(byte[] regionName) throws IOException;
518
519  /**
520   * Flush all regions on the region server. Synchronous operation.
521   * @param serverName the region server name to flush
522   * @throws IOException if a remote or network exception occurs
523   */
524  void flushRegionServer(ServerName serverName) throws IOException;
525
526  /**
527   * Compact a table. Asynchronous operation in that this method requests that a
528   * Compaction run and then it returns. It does not wait on the completion of Compaction
529   * (it can take a while).
530   *
531   * @param tableName table to compact
532   * @throws IOException if a remote or network exception occurs
533   */
534  void compact(TableName tableName) throws IOException;
535
536  /**
537   * Compact an individual region. Asynchronous operation in that this method requests that a
538   * Compaction run and then it returns. It does not wait on the completion of Compaction
539   * (it can take a while).
540   *
541   * @param regionName region to compact
542   * @throws IOException if a remote or network exception occurs
543   */
544  void compactRegion(byte[] regionName) throws IOException;
545
546  /**
547   * Compact a column family within a table. Asynchronous operation in that this method requests
548   * that a Compaction run and then it returns. It does not wait on the completion of Compaction
549   * (it can take a while).
550   *
551   * @param tableName table to compact
552   * @param columnFamily column family within a table
553   * @throws IOException if a remote or network exception occurs
554   */
555  void compact(TableName tableName, byte[] columnFamily)
556    throws IOException;
557
558  /**
559   * Compact a column family within a region. Asynchronous operation in that this method requests
560   * that a Compaction run and then it returns. It does not wait on the completion of Compaction
561   * (it can take a while).
562   *
563   * @param regionName region to compact
564   * @param columnFamily column family within a region
565   * @throws IOException if a remote or network exception occurs
566   */
567  void compactRegion(byte[] regionName, byte[] columnFamily)
568    throws IOException;
569
570  /**
571   * Compact a table.  Asynchronous operation in that this method requests that a
572   * Compaction run and then it returns. It does not wait on the completion of Compaction
573   * (it can take a while).
574   *
575   * @param tableName table to compact
576   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
577   * @throws IOException if a remote or network exception occurs
578   * @throws InterruptedException
579   */
580  void compact(TableName tableName, CompactType compactType)
581    throws IOException, InterruptedException;
582
583  /**
584   * Compact a column family within a table.  Asynchronous operation in that this method
585   * requests that a Compaction run and then it returns. It does not wait on the
586   * completion of Compaction (it can take a while).
587   *
588   * @param tableName table to compact
589   * @param columnFamily column family within a table
590   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
591   * @throws IOException if not a mob column family or if a remote or network exception occurs
592   * @throws InterruptedException
593   */
594  void compact(TableName tableName, byte[] columnFamily, CompactType compactType)
595    throws IOException, InterruptedException;
596
597  /**
598   * Major compact a table. Asynchronous operation in that this method requests
599   * that a Compaction run and then it returns. It does not wait on the completion of Compaction
600   * (it can take a while).
601   *
602   * @param tableName table to major compact
603   * @throws IOException if a remote or network exception occurs
604   */
605  void majorCompact(TableName tableName) throws IOException;
606
607  /**
608   * Major compact a table or an individual region. Asynchronous operation in that this method requests
609   * that a Compaction run and then it returns. It does not wait on the completion of Compaction
610   * (it can take a while).
611   *
612   * @param regionName region to major compact
613   * @throws IOException if a remote or network exception occurs
614   */
615  void majorCompactRegion(byte[] regionName) throws IOException;
616
617  /**
618   * Major compact a column family within a table. Asynchronous operation in that this method requests
619   * that a Compaction run and then it returns. It does not wait on the completion of Compaction
620   * (it can take a while).
621   *
622   * @param tableName table to major compact
623   * @param columnFamily column family within a table
624   * @throws IOException if a remote or network exception occurs
625   */
626  void majorCompact(TableName tableName, byte[] columnFamily)
627    throws IOException;
628
629  /**
630   * Major compact a column family within region. Asynchronous operation in that this method requests
631   * that a Compaction run and then it returns. It does not wait on the completion of Compaction
632   * (it can take a while).
633   *
634   * @param regionName egion to major compact
635   * @param columnFamily column family within a region
636   * @throws IOException if a remote or network exception occurs
637   */
638  void majorCompactRegion(byte[] regionName, byte[] columnFamily)
639    throws IOException;
640
641  /**
642   * Major compact a table.  Asynchronous operation in that this method requests that a
643   * Compaction run and then it returns. It does not wait on the completion of Compaction
644   * (it can take a while).
645   *
646   * @param tableName table to compact
647   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
648   * @throws IOException if a remote or network exception occurs
649   * @throws InterruptedException
650   */
651  void majorCompact(TableName tableName, CompactType compactType)
652    throws IOException, InterruptedException;
653
654  /**
655   * Major compact a column family within a table.  Asynchronous operation in that this method requests that a
656   * Compaction run and then it returns. It does not wait on the completion of Compaction
657   * (it can take a while).
658   *
659   * @param tableName table to compact
660   * @param columnFamily column family within a table
661   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
662   * @throws IOException if not a mob column family or if a remote or network exception occurs
663   * @throws InterruptedException
664   */
665  void majorCompact(TableName tableName, byte[] columnFamily, CompactType compactType)
666    throws IOException, InterruptedException;
667
668  /**
669   * Turn the compaction on or off. Disabling compactions will also interrupt any currently ongoing
670   * compactions. This state is ephemeral. The setting will be lost on restart. Compaction
671   * can also be enabled/disabled by modifying configuration hbase.regionserver.compaction.enabled
672   * in hbase-site.xml.
673   *
674   * @param switchState     Set to <code>true</code> to enable, <code>false</code> to disable.
675   * @param serverNamesList list of region servers.
676   * @return Previous compaction states for region servers
677   * @throws IOException if a remote or network exception occurs
678   */
679  Map<ServerName, Boolean> compactionSwitch(boolean switchState, List<String> serverNamesList)
680      throws IOException;
681
682  /**
683   * Compact all regions on the region server. Asynchronous operation in that this method requests
684   * that a Compaction run and then it returns. It does not wait on the completion of Compaction (it
685   * can take a while).
686   * @param serverName the region server name
687   * @throws IOException if a remote or network exception occurs
688   */
689  void compactRegionServer(ServerName serverName) throws IOException;
690
691  /**
692   * Major compact all regions on the region server. Asynchronous operation in that this method
693   * requests that a Compaction run and then it returns. It does not wait on the completion of
694   * Compaction (it can take a while).
695   * @param serverName the region server name
696   * @throws IOException if a remote or network exception occurs
697   */
698  void majorCompactRegionServer(ServerName serverName) throws IOException;
699
700  /**
701   * Move the region <code>encodedRegionName</code> to a random server.
702   * @param encodedRegionName The encoded region name; i.e. the hash that makes up the region name
703   *          suffix: e.g. if regionname is
704   *          <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>,
705   *          then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>.
706   * @throws IOException if we can't find a region named <code>encodedRegionName</code>
707   */
708  void move(byte[] encodedRegionName) throws IOException;
709
710  /**
711   * Move the region <code>rencodedRegionName</code> to <code>destServerName</code>.
712   * @param encodedRegionName The encoded region name; i.e. the hash that makes up the region name
713   *          suffix: e.g. if regionname is
714   *          <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>,
715   *          then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>.
716   * @param destServerName The servername of the destination regionserver. If passed the empty byte
717   *          array we'll assign to a random server. A server name is made of host, port and
718   *          startcode. Here is an example: <code> host187.example.com,60020,1289493121758</code>
719   * @throws IOException if we can't find a region named <code>encodedRegionName</code>
720   * @deprecated since 2.2.0 and will be removed in 4.0.0. Use {@link #move(byte[], ServerName)}
721   *   instead. And if you want to move the region to a random server, please use
722   *   {@link #move(byte[])}.
723   * @see <a href="https://issues.apache.org/jira/browse/HBASE-22108">HBASE-22108</a>
724   */
725  @Deprecated
726  default void move(byte[] encodedRegionName, byte[] destServerName) throws IOException {
727    if (destServerName == null || destServerName.length == 0) {
728      move(encodedRegionName);
729    } else {
730      move(encodedRegionName, ServerName.valueOf(Bytes.toString(destServerName)));
731    }
732  }
733
734  /**
735   * Move the region <code>encodedRegionName</code> to <code>destServerName</code>.
736   * @param encodedRegionName The encoded region name; i.e. the hash that makes up the region name
737   *          suffix: e.g. if regionname is
738   *          <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>,
739   *          then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>.
740   * @param destServerName The servername of the destination regionserver. A server name is made of
741   *          host, port and startcode. Here is an example:
742   *          <code> host187.example.com,60020,1289493121758</code>
743   * @throws IOException if we can't find a region named <code>encodedRegionName</code>
744   */
745  void move(byte[] encodedRegionName, ServerName destServerName) throws IOException;
746
747  /**
748   * Assign a Region.
749   * @param regionName Region name to assign.
750   * @throws IOException if a remote or network exception occurs
751   */
752  void assign(byte[] regionName) throws IOException;
753
754  /**
755   * Unassign a region from current hosting regionserver.  Region will then be assigned to a
756   * regionserver chosen at random.  Region could be reassigned back to the same server.  Use {@link
757   * #move(byte[], ServerName)} if you want to control the region movement.
758   *
759   * @param regionName Region to unassign. Will clear any existing RegionPlan if one found.
760   * @param force If <code>true</code>, force unassign (Will remove region from regions-in-transition too if
761   * present. If results in double assignment use hbck -fix to resolve. To be used by experts).
762   * @throws IOException if a remote or network exception occurs
763   */
764  void unassign(byte[] regionName, boolean force)
765      throws IOException;
766
767  /**
768   * Offline specified region from master's in-memory state. It will not attempt to reassign the
769   * region as in unassign. This API can be used when a region not served by any region server and
770   * still online as per Master's in memory state. If this API is incorrectly used on active region
771   * then master will loose track of that region. This is a special method that should be used by
772   * experts or hbck.
773   *
774   * @param regionName Region to offline.
775   * @throws IOException if a remote or network exception occurs
776   */
777  void offline(byte[] regionName) throws IOException;
778
779  /**
780   * Turn the load balancer on or off.
781   * @param onOrOff Set to <code>true</code> to enable, <code>false</code> to disable.
782   * @param synchronous If <code>true</code>, it waits until current balance() call, if outstanding,
783   *          to return.
784   * @return Previous balancer value
785   * @throws IOException if a remote or network exception occurs
786   */
787  boolean balancerSwitch(boolean onOrOff, boolean synchronous) throws IOException;
788
789  /**
790   * Invoke the balancer.  Will run the balancer and if regions to move, it will go ahead and do the
791   * reassignments.  Can NOT run for various reasons.  Check logs.
792   *
793   * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
794   * @throws IOException if a remote or network exception occurs
795   */
796  boolean balance() throws IOException;
797
798  /**
799   * Invoke the balancer.  Will run the balancer and if regions to move, it will
800   * go ahead and do the reassignments. If there is region in transition, force parameter of true
801   * would still run balancer. Can *not* run for other reasons.  Check
802   * logs.
803   * @param force whether we should force balance even if there is region in transition
804   * @return <code>true</code> if balancer ran, <code>false</code> otherwise.
805   * @throws IOException if a remote or network exception occurs
806   */
807  boolean balance(boolean force) throws IOException;
808
809  /**
810   * Query the current state of the balancer.
811   *
812   * @return <code>true</code> if the balancer is enabled, <code>false</code> otherwise.
813   * @throws IOException if a remote or network exception occurs
814   */
815  boolean isBalancerEnabled() throws IOException;
816
817  /**
818   * Clear all the blocks corresponding to this table from BlockCache. For expert-admins.
819   * Calling this API will drop all the cached blocks specific to a table from BlockCache.
820   * This can significantly impact the query performance as the subsequent queries will
821   * have to retrieve the blocks from underlying filesystem.
822   *
823   * @param tableName table to clear block cache
824   * @return CacheEvictionStats related to the eviction
825   * @throws IOException if a remote or network exception occurs
826   */
827  CacheEvictionStats clearBlockCache(final TableName tableName) throws IOException;
828
829  /**
830   * Invoke region normalizer. Can NOT run for various reasons.  Check logs.
831   *
832   * @return <code>true</code> if region normalizer ran, <code>false</code> otherwise.
833   * @throws IOException if a remote or network exception occurs
834   */
835  boolean normalize() throws IOException;
836
837  /**
838   * Query the current state of the region normalizer.
839   *
840   * @return <code>true</code> if region normalizer is enabled, <code>false</code> otherwise.
841   * @throws IOException if a remote or network exception occurs
842   */
843  boolean isNormalizerEnabled() throws IOException;
844
845  /**
846   * Turn region normalizer on or off.
847   *
848   * @return Previous normalizer value
849   * @throws IOException if a remote or network exception occurs
850   */
851  boolean normalizerSwitch(boolean on) throws IOException;
852
853  /**
854   * Enable/Disable the catalog janitor/
855   *
856   * @param onOrOff if <code>true</code> enables the catalog janitor
857   * @return the previous state
858   * @throws IOException if a remote or network exception occurs
859   */
860  boolean catalogJanitorSwitch(boolean onOrOff) throws IOException;
861
862  /**
863   * Ask for a scan of the catalog table.
864   *
865   * @return the number of entries cleaned
866   * @throws IOException if a remote or network exception occurs
867   */
868  int runCatalogJanitor() throws IOException;
869
870  /**
871   * Query on the catalog janitor state (Enabled/Disabled?).
872   *
873   * @throws IOException if a remote or network exception occurs
874   */
875  boolean isCatalogJanitorEnabled() throws IOException;
876
877  /**
878   * Enable/Disable the cleaner chore.
879   *
880   * @param onOrOff if <code>true</code> enables the cleaner chore
881   * @return the previous state
882   * @throws IOException if a remote or network exception occurs
883   */
884  boolean cleanerChoreSwitch(boolean onOrOff) throws IOException;
885
886  /**
887   * Ask for cleaner chore to run.
888   *
889   * @return <code>true</code> if cleaner chore ran, <code>false</code> otherwise
890   * @throws IOException if a remote or network exception occurs
891   */
892  boolean runCleanerChore() throws IOException;
893
894  /**
895   * Query on the cleaner chore state (Enabled/Disabled?).
896   *
897   * @throws IOException if a remote or network exception occurs
898   */
899  boolean isCleanerChoreEnabled() throws IOException;
900
901
902  /**
903   * Merge two regions. Asynchronous operation.
904   * @param nameOfRegionA encoded or full name of region a
905   * @param nameOfRegionB encoded or full name of region b
906   * @param forcible <code>true</code> if do a compulsory merge, otherwise we will only merge two
907   *          adjacent regions
908   * @throws IOException if a remote or network exception occurs
909   * @deprecated since 2.3.0 and will be removed in 4.0.0. Multi-region merge feature is now
910   *             supported. Use {@link #mergeRegionsAsync(byte[][], boolean)} instead.
911   */
912  @Deprecated
913  default Future<Void> mergeRegionsAsync(byte[] nameOfRegionA, byte[] nameOfRegionB,
914      boolean forcible) throws IOException {
915    byte[][] nameofRegionsToMerge = new byte[2][];
916    nameofRegionsToMerge[0] = nameOfRegionA;
917    nameofRegionsToMerge[1] = nameOfRegionB;
918    return mergeRegionsAsync(nameofRegionsToMerge, forcible);
919  }
920
921  /**
922   * Merge multiple regions (>=2). Asynchronous operation.
923   * @param nameofRegionsToMerge encoded or full name of daughter regions
924   * @param forcible <code>true</code> if do a compulsory merge, otherwise we will only merge
925   *          adjacent regions
926   * @throws IOException if a remote or network exception occurs
927   */
928  Future<Void> mergeRegionsAsync(byte[][] nameofRegionsToMerge, boolean forcible)
929      throws IOException;
930
931  /**
932   * Split a table. The method will execute split action for each region in table.
933   * @param tableName table to split
934   * @throws IOException if a remote or network exception occurs
935   */
936  void split(TableName tableName) throws IOException;
937
938  /**
939   * Split a table.
940   * @param tableName table to split
941   * @param splitPoint the explicit position to split on
942   * @throws IOException if a remote or network exception occurs
943   */
944  void split(TableName tableName, byte[] splitPoint) throws IOException;
945
946  /**
947   * Split an individual region. Asynchronous operation.
948   * @param regionName region to split
949   * @throws IOException if a remote or network exception occurs
950   */
951  Future<Void> splitRegionAsync(byte[] regionName) throws IOException;
952
953  /**
954   * Split an individual region. Asynchronous operation.
955   * @param regionName region to split
956   * @param splitPoint the explicit position to split on
957   * @throws IOException if a remote or network exception occurs
958   */
959  Future<Void> splitRegionAsync(byte[] regionName, byte[] splitPoint) throws IOException;
960
961  /**
962   * Modify an existing table, more IRB friendly version.
963   * @param td modified description of the table
964   * @throws IOException if a remote or network exception occurs
965   */
966  default void modifyTable(TableDescriptor td) throws IOException {
967    get(modifyTableAsync(td), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
968  }
969
970  /**
971   * Modify an existing table, more IRB (ruby) friendly version. Asynchronous operation. This means
972   * that it may be a while before your schema change is updated across all of the table. You can
973   * use Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
974   * ExecutionException if there was an error while executing the operation or TimeoutException in
975   * case the wait timeout was not long enough to allow the operation to complete.
976   * @param td description of the table
977   * @throws IOException if a remote or network exception occurs
978   * @return the result of the async modify. You can use Future.get(long, TimeUnit) to wait on the
979   *         operation to complete
980   */
981  Future<Void> modifyTableAsync(TableDescriptor td) throws IOException;
982
983  /**
984   * Shuts down the HBase cluster.
985   * <p/>
986   * Notice that, a success shutdown call may ends with an error since the remote server has already
987   * been shutdown.
988   * @throws IOException if a remote or network exception occurs
989   */
990  void shutdown() throws IOException;
991
992  /**
993   * Shuts down the current HBase master only. Does not shutdown the cluster.
994   * <p/>
995   * Notice that, a success stopMaster call may ends with an error since the remote server has
996   * already been shutdown.
997   * @throws IOException if a remote or network exception occurs
998   * @see #shutdown()
999   */
1000  void stopMaster() throws IOException;
1001
1002  /**
1003   * Check whether Master is in maintenance mode.
1004   *
1005   * @throws IOException if a remote or network exception occurs
1006   */
1007  boolean isMasterInMaintenanceMode()  throws IOException;
1008
1009  /**
1010   * Stop the designated regionserver.
1011   *
1012   * @param hostnamePort Hostname and port delimited by a <code>:</code> as in
1013   * <code>example.org:1234</code>
1014   * @throws IOException if a remote or network exception occurs
1015   */
1016  void stopRegionServer(String hostnamePort) throws IOException;
1017
1018  /**
1019   * Get whole cluster metrics, containing status about:
1020   * <pre>
1021   * hbase version
1022   * cluster id
1023   * primary/backup master(s)
1024   * master's coprocessors
1025   * live/dead regionservers
1026   * balancer
1027   * regions in transition
1028   * </pre>
1029   * @return cluster metrics
1030   * @throws IOException if a remote or network exception occurs
1031   */
1032  default ClusterMetrics getClusterMetrics() throws IOException {
1033    return getClusterMetrics(EnumSet.allOf(ClusterMetrics.Option.class));
1034  }
1035
1036  /**
1037   * Get cluster status with a set of {@link Option} to get desired status.
1038   * @return cluster status
1039   * @throws IOException if a remote or network exception occurs
1040   */
1041  ClusterMetrics getClusterMetrics(EnumSet<Option> options) throws IOException;
1042
1043  /**
1044   * @return current master server name
1045   * @throws IOException if a remote or network exception occurs
1046   */
1047  default ServerName getMaster() throws IOException {
1048    return getClusterMetrics(EnumSet.of(Option.MASTER)).getMasterName();
1049  }
1050
1051  /**
1052   * @return current backup master list
1053   * @throws IOException if a remote or network exception occurs
1054   */
1055  default Collection<ServerName> getBackupMasters() throws IOException {
1056    return getClusterMetrics(EnumSet.of(Option.BACKUP_MASTERS)).getBackupMasterNames();
1057  }
1058
1059  /**
1060   * @return current live region servers list
1061   * @throws IOException if a remote or network exception occurs
1062   */
1063  default Collection<ServerName> getRegionServers() throws IOException {
1064    return getClusterMetrics(EnumSet.of(Option.SERVERS_NAME)).getServersName();
1065  }
1066
1067  /**
1068   * Get {@link RegionMetrics} of all regions hosted on a regionserver.
1069   *
1070   * @param serverName region server from which {@link RegionMetrics} is required.
1071   * @return a {@link RegionMetrics} list of all regions hosted on a region server
1072   * @throws IOException if a remote or network exception occurs
1073   */
1074  List<RegionMetrics> getRegionMetrics(ServerName serverName) throws IOException;
1075
1076  /**
1077   * Get {@link RegionMetrics} of all regions hosted on a regionserver for a table.
1078   *
1079   * @param serverName region server from which {@link RegionMetrics} is required.
1080   * @param tableName get {@link RegionMetrics} of regions belonging to the table
1081   * @return region metrics map of all regions of a table hosted on a region server
1082   * @throws IOException if a remote or network exception occurs
1083   */
1084  List<RegionMetrics> getRegionMetrics(ServerName serverName,
1085    TableName tableName) throws IOException;
1086
1087  /**
1088   * @return Configuration used by the instance.
1089   */
1090  Configuration getConfiguration();
1091
1092  /**
1093   * Create a new namespace. Blocks until namespace has been successfully created or an exception is
1094   * thrown.
1095   * @param descriptor descriptor which describes the new namespace.
1096   * @throws IOException if a remote or network exception occurs
1097   */
1098  default void createNamespace(NamespaceDescriptor descriptor) throws IOException {
1099    get(createNamespaceAsync(descriptor), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
1100  }
1101
1102  /**
1103   * Create a new namespace.
1104   * @param descriptor descriptor which describes the new namespace
1105   * @return the result of the async create namespace operation. Use Future.get(long, TimeUnit) to
1106   *         wait on the operation to complete.
1107   * @throws IOException if a remote or network exception occurs
1108   */
1109  Future<Void> createNamespaceAsync(NamespaceDescriptor descriptor) throws IOException;
1110
1111  /**
1112   * Modify an existing namespace. Blocks until namespace has been successfully modified or an
1113   * exception is thrown.
1114   * @param descriptor descriptor which describes the new namespace
1115   * @throws IOException if a remote or network exception occurs
1116   */
1117  default void modifyNamespace(NamespaceDescriptor descriptor) throws IOException {
1118    get(modifyNamespaceAsync(descriptor), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
1119  }
1120
1121  /**
1122   * Modify an existing namespace.
1123   * @param descriptor descriptor which describes the new namespace
1124   * @return the result of the async modify namespace operation. Use Future.get(long, TimeUnit) to
1125   *         wait on the operation to complete.
1126   * @throws IOException if a remote or network exception occurs
1127   */
1128  Future<Void> modifyNamespaceAsync(NamespaceDescriptor descriptor) throws IOException;
1129
1130  /**
1131   * Delete an existing namespace. Only empty namespaces (no tables) can be removed. Blocks until
1132   * namespace has been successfully deleted or an exception is thrown.
1133   * @param name namespace name
1134   * @throws IOException if a remote or network exception occurs
1135   */
1136  default void deleteNamespace(String name) throws IOException {
1137    get(deleteNamespaceAsync(name), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
1138  }
1139
1140  /**
1141   * Delete an existing namespace. Only empty namespaces (no tables) can be removed.
1142   * @param name namespace name
1143   * @return the result of the async delete namespace operation. Use Future.get(long, TimeUnit) to
1144   *         wait on the operation to complete.
1145   * @throws IOException if a remote or network exception occurs
1146   */
1147  Future<Void> deleteNamespaceAsync(String name) throws IOException;
1148
1149  /**
1150   * Get a namespace descriptor by name.
1151   * @param name name of namespace descriptor
1152   * @return A descriptor
1153   * @throws org.apache.hadoop.hbase.NamespaceNotFoundException
1154   * @throws IOException if a remote or network exception occurs
1155   */
1156  NamespaceDescriptor getNamespaceDescriptor(String name)
1157      throws NamespaceNotFoundException, IOException;
1158
1159  /**
1160   * List available namespaces
1161   *
1162   * @return List of namespace names
1163   * @throws IOException if a remote or network exception occurs
1164   */
1165  String[] listNamespaces() throws IOException;
1166
1167  /**
1168   * List available namespace descriptors
1169   *
1170   * @return List of descriptors
1171   * @throws IOException if a remote or network exception occurs
1172   */
1173  NamespaceDescriptor[] listNamespaceDescriptors() throws IOException;
1174
1175  /**
1176   * Get list of table descriptors by namespace.
1177   * @param name namespace name
1178   * @return returns a list of TableDescriptors
1179   * @throws IOException if a remote or network exception occurs
1180   */
1181  List<TableDescriptor> listTableDescriptorsByNamespace(byte[] name) throws IOException;
1182
1183  /**
1184   * Get list of table names by namespace.
1185   * @param name namespace name
1186   * @return The list of table names in the namespace
1187   * @throws IOException if a remote or network exception occurs
1188   */
1189  TableName[] listTableNamesByNamespace(String name) throws IOException;
1190
1191  /**
1192   * Get the regions of a given table.
1193   *
1194   * @param tableName the name of the table
1195   * @return List of {@link RegionInfo}.
1196   * @throws IOException if a remote or network exception occurs
1197   */
1198  List<RegionInfo> getRegions(TableName tableName) throws IOException;
1199
1200  @Override
1201  void close();
1202
1203  /**
1204   * Get tableDescriptors.
1205   *
1206   * @param tableNames List of table names
1207   * @return returns a list of TableDescriptors
1208   * @throws IOException if a remote or network exception occurs
1209   */
1210  List<TableDescriptor> listTableDescriptors(List<TableName> tableNames)
1211    throws IOException;
1212
1213  /**
1214   * Abort a procedure.
1215   * <p/>
1216   * Do not use. Usually it is ignored but if not, it can do more damage than good. See hbck2.
1217   * @param procId ID of the procedure to abort
1218   * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
1219   * @return <code>true</code> if aborted, <code>false</code> if procedure already completed or does
1220   *         not exist
1221   * @throws IOException if a remote or network exception occurs
1222   * @deprecated since 2.1.1 and will be removed in 4.0.0.
1223   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
1224   */
1225  @Deprecated
1226  default boolean abortProcedure(long procId, boolean mayInterruptIfRunning) throws IOException {
1227    return get(abortProcedureAsync(procId, mayInterruptIfRunning), getSyncWaitTimeout(),
1228      TimeUnit.MILLISECONDS);
1229  }
1230
1231  /**
1232   * Abort a procedure but does not block and wait for completion.
1233   * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
1234   * It may throw ExecutionException if there was an error while executing the operation
1235   * or TimeoutException in case the wait timeout was not long enough to allow the
1236   * operation to complete.
1237   * Do not use. Usually it is ignored but if not, it can do more damage than good. See hbck2.
1238   *
1239   * @param procId ID of the procedure to abort
1240   * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
1241   * @return <code>true</code> if aborted, <code>false</code> if procedure already completed or does not exist
1242   * @throws IOException if a remote or network exception occurs
1243   * @deprecated since 2.1.1 and will be removed in 4.0.0.
1244   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
1245   */
1246  @Deprecated
1247  Future<Boolean> abortProcedureAsync(long procId, boolean mayInterruptIfRunning)
1248      throws IOException;
1249
1250  /**
1251   * Get procedures.
1252   * @return procedure list in JSON
1253   * @throws IOException if a remote or network exception occurs
1254   */
1255  String getProcedures() throws IOException;
1256
1257  /**
1258   * Get locks.
1259   * @return lock list in JSON
1260   * @throws IOException if a remote or network exception occurs
1261   */
1262  String getLocks() throws IOException;
1263
1264  /**
1265   * Roll the log writer. I.e. for filesystem based write ahead logs, start writing to a new file.
1266   *
1267   * Note that the actual rolling of the log writer is asynchronous and may not be complete when
1268   * this method returns. As a side effect of this call, the named region server may schedule
1269   * store flushes at the request of the wal.
1270   *
1271   * @param serverName The servername of the regionserver.
1272   * @throws IOException if a remote or network exception occurs
1273   * @throws org.apache.hadoop.hbase.regionserver.wal.FailedLogCloseException
1274   */
1275  void rollWALWriter(ServerName serverName) throws IOException, FailedLogCloseException;
1276
1277  /**
1278   * Helper that delegates to getClusterMetrics().getMasterCoprocessorNames().
1279   * @return an array of master coprocessors
1280   * @see org.apache.hadoop.hbase.ClusterMetrics#getMasterCoprocessorNames()
1281   */
1282  default List<String> getMasterCoprocessorNames() throws IOException {
1283    return getClusterMetrics(EnumSet.of(Option.MASTER_COPROCESSORS))
1284      .getMasterCoprocessorNames();
1285  }
1286
1287  /**
1288   * Get the current compaction state of a table. It could be in a major compaction, a minor
1289   * compaction, both, or none.
1290   *
1291   * @param tableName table to examine
1292   * @return the current compaction state
1293   * @throws IOException if a remote or network exception occurs
1294   */
1295  CompactionState getCompactionState(TableName tableName) throws IOException;
1296
1297  /**
1298   * Get the current compaction state of a table. It could be in a compaction, or none.
1299   *
1300   * @param tableName table to examine
1301   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
1302   * @return the current compaction state
1303   * @throws IOException if a remote or network exception occurs
1304   */
1305  CompactionState getCompactionState(TableName tableName,
1306    CompactType compactType) throws IOException;
1307
1308  /**
1309   * Get the current compaction state of region. It could be in a major compaction, a minor
1310   * compaction, both, or none.
1311   *
1312   * @param regionName region to examine
1313   * @return the current compaction state
1314   * @throws IOException if a remote or network exception occurs
1315   */
1316  CompactionState getCompactionStateForRegion(byte[] regionName) throws IOException;
1317
1318  /**
1319   * Get the timestamp of the last major compaction for the passed table
1320   *
1321   * The timestamp of the oldest HFile resulting from a major compaction of that table,
1322   * or 0 if no such HFile could be found.
1323   *
1324   * @param tableName table to examine
1325   * @return the last major compaction timestamp or 0
1326   * @throws IOException if a remote or network exception occurs
1327   */
1328  long getLastMajorCompactionTimestamp(TableName tableName) throws IOException;
1329
1330  /**
1331   * Get the timestamp of the last major compaction for the passed region.
1332   *
1333   * The timestamp of the oldest HFile resulting from a major compaction of that region,
1334   * or 0 if no such HFile could be found.
1335   *
1336   * @param regionName region to examine
1337   * @return the last major compaction timestamp or 0
1338   * @throws IOException if a remote or network exception occurs
1339   */
1340  long getLastMajorCompactionTimestampForRegion(byte[] regionName) throws IOException;
1341
1342  /**
1343   * Take a snapshot for the given table. If the table is enabled, a FLUSH-type snapshot will be
1344   * taken. If the table is disabled, an offline snapshot is taken. Snapshots are taken
1345   * sequentially even when requested concurrently, across all tables. Snapshots are considered
1346   * unique based on <b>the name of the snapshot</b>. Attempts to take a snapshot with the same
1347   * name (even a different type or with different parameters) will fail with a
1348   * {@link org.apache.hadoop.hbase.snapshot.SnapshotCreationException} indicating the duplicate
1349   * naming. Snapshot names follow the same naming constraints as tables in HBase. See
1350   * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
1351   * @param snapshotName name of the snapshot to be created
1352   * @param tableName name of the table for which snapshot is created
1353   * @throws IOException if a remote or network exception occurs
1354   * @throws org.apache.hadoop.hbase.snapshot.SnapshotCreationException if snapshot creation failed
1355   * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1356   */
1357  default void snapshot(String snapshotName, TableName tableName)
1358      throws IOException, SnapshotCreationException, IllegalArgumentException {
1359    snapshot(snapshotName, tableName, SnapshotType.FLUSH);
1360  }
1361
1362  /**
1363   * Create typed snapshot of the table. Snapshots are considered unique based on <b>the name of the
1364   * snapshot</b>. Snapshots are taken sequentially even when requested concurrently, across
1365   * all tables. Attempts to take a snapshot with the same name (even a different type or with
1366   * different parameters) will fail with a {@link SnapshotCreationException} indicating the
1367   * duplicate naming. Snapshot names follow the same naming constraints as tables in HBase. See
1368   * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
1369   * @param snapshotName name to give the snapshot on the filesystem. Must be unique from all other
1370   *          snapshots stored on the cluster
1371   * @param tableName name of the table to snapshot
1372   * @param type type of snapshot to take
1373   * @throws IOException we fail to reach the master
1374   * @throws SnapshotCreationException if snapshot creation failed
1375   * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1376   */
1377  default void snapshot(String snapshotName, TableName tableName, SnapshotType type)
1378      throws IOException, SnapshotCreationException, IllegalArgumentException {
1379    snapshot(new SnapshotDescription(snapshotName, tableName, type));
1380  }
1381
1382  /**
1383   * Create typed snapshot of the table. Snapshots are considered unique based on <b>the name of the
1384   * snapshot</b>. Snapshots are taken sequentially even when requested concurrently, across
1385   * all tables. Attempts to take a snapshot with the same name (even a different type or with
1386   * different parameters) will fail with a {@link SnapshotCreationException} indicating the
1387   * duplicate naming. Snapshot names follow the same naming constraints as tables in HBase. See
1388   * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
1389   * Snapshot can live with ttl seconds.
1390   *
1391   * @param snapshotName  name to give the snapshot on the filesystem. Must be unique from all other
1392   *                      snapshots stored on the cluster
1393   * @param tableName     name of the table to snapshot
1394   * @param type          type of snapshot to take
1395   * @param snapshotProps snapshot additional properties e.g. TTL
1396   * @throws IOException               we fail to reach the master
1397   * @throws SnapshotCreationException if snapshot creation failed
1398   * @throws IllegalArgumentException  if the snapshot request is formatted incorrectly
1399   */
1400  default void snapshot(String snapshotName, TableName tableName, SnapshotType type,
1401                        Map<String, Object> snapshotProps) throws IOException,
1402      SnapshotCreationException, IllegalArgumentException {
1403    snapshot(new SnapshotDescription(snapshotName, tableName, type, snapshotProps));
1404  }
1405
1406  /**
1407   * Create typed snapshot of the table. Snapshots are considered unique based on <b>the name of the
1408   * snapshot</b>. Snapshots are taken sequentially even when requested concurrently, across
1409   * all tables. Attempts to take a snapshot with the same name (even a different type or with
1410   * different parameters) will fail with a {@link SnapshotCreationException} indicating the
1411   * duplicate naming. Snapshot names follow the same naming constraints as tables in HBase. See
1412   * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
1413   * Snapshot can live with ttl seconds.
1414   *
1415   * @param snapshotName  name to give the snapshot on the filesystem. Must be unique from all other
1416   *                      snapshots stored on the cluster
1417   * @param tableName     name of the table to snapshot
1418   * @param snapshotProps snapshot additional properties e.g. TTL
1419   * @throws IOException               we fail to reach the master
1420   * @throws SnapshotCreationException if snapshot creation failed
1421   * @throws IllegalArgumentException  if the snapshot request is formatted incorrectly
1422   */
1423  default void snapshot(String snapshotName, TableName tableName,
1424                        Map<String, Object> snapshotProps) throws IOException,
1425      SnapshotCreationException, IllegalArgumentException {
1426    snapshot(new SnapshotDescription(snapshotName, tableName, SnapshotType.FLUSH, snapshotProps));
1427  }
1428
1429  /**
1430   * Take a snapshot and wait for the server to complete that snapshot (blocking). Snapshots are
1431   * considered unique based on <b>the name of the snapshot</b>. Snapshots are taken sequentially
1432   * even when requested concurrently, across all tables. Attempts to take a snapshot with the same
1433   * name (even a different type or with different parameters) will fail with a
1434   * {@link SnapshotCreationException} indicating the duplicate naming. Snapshot names follow the
1435   * same naming constraints as tables in HBase. See
1436   * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}. You should
1437   * probably use {@link #snapshot(String, org.apache.hadoop.hbase.TableName)} unless you are sure
1438   * about the type of snapshot that you want to take.
1439   * @param snapshot snapshot to take
1440   * @throws IOException or we lose contact with the master.
1441   * @throws SnapshotCreationException if snapshot failed to be taken
1442   * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1443   */
1444  void snapshot(SnapshotDescription snapshot)
1445      throws IOException, SnapshotCreationException, IllegalArgumentException;
1446
1447  /**
1448   * Take a snapshot without waiting for the server to complete that snapshot (asynchronous).
1449   * Snapshots are considered unique based on <b>the name of the snapshot</b>. Snapshots are taken
1450   * sequentially even when requested concurrently, across all tables.
1451   *
1452   * @param snapshot snapshot to take
1453   * @throws IOException if the snapshot did not succeed or we lose contact with the master.
1454   * @throws SnapshotCreationException if snapshot creation failed
1455   * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1456   */
1457  Future<Void> snapshotAsync(SnapshotDescription snapshot)
1458      throws IOException, SnapshotCreationException;
1459
1460  /**
1461   * Check the current state of the passed snapshot. There are three possible states: <ol>
1462   * <li>running - returns <tt>false</tt></li> <li>finished - returns <tt>true</tt></li>
1463   * <li>finished with error - throws the exception that caused the snapshot to fail</li> </ol> The
1464   * cluster only knows about the most recent snapshot. Therefore, if another snapshot has been
1465   * run/started since the snapshot you are checking, you will receive an {@link
1466   * org.apache.hadoop.hbase.snapshot.UnknownSnapshotException}.
1467   *
1468   * @param snapshot description of the snapshot to check
1469   * @return <tt>true</tt> if the snapshot is completed, <tt>false</tt> if the snapshot is still
1470   * running
1471   * @throws IOException if we have a network issue
1472   * @throws org.apache.hadoop.hbase.snapshot.HBaseSnapshotException if the snapshot failed
1473   * @throws org.apache.hadoop.hbase.snapshot.UnknownSnapshotException if the requested snapshot is
1474   * unknown
1475   */
1476  boolean isSnapshotFinished(SnapshotDescription snapshot)
1477      throws IOException, HBaseSnapshotException, UnknownSnapshotException;
1478
1479  /**
1480   * Restore the specified snapshot on the original table. (The table must be disabled) If the
1481   * "hbase.snapshot.restore.take.failsafe.snapshot" configuration property is set to
1482   * <code>true</code>, a snapshot of the current table is taken before executing the restore
1483   * operation. In case of restore failure, the failsafe snapshot will be restored. If the restore
1484   * completes without problem the failsafe snapshot is deleted.
1485   * @param snapshotName name of the snapshot to restore
1486   * @throws IOException if a remote or network exception occurs
1487   * @throws RestoreSnapshotException if snapshot failed to be restored
1488   * @throws IllegalArgumentException if the restore request is formatted incorrectly
1489   */
1490  void restoreSnapshot(String snapshotName) throws IOException, RestoreSnapshotException;
1491
1492  /**
1493   * Restore the specified snapshot on the original table. (The table must be disabled) If
1494   * 'takeFailSafeSnapshot' is set to <code>true</code>, a snapshot of the current table is taken
1495   * before executing the restore operation. In case of restore failure, the failsafe snapshot will
1496   * be restored. If the restore completes without problem the failsafe snapshot is deleted. The
1497   * failsafe snapshot name is configurable by using the property
1498   * "hbase.snapshot.restore.failsafe.name".
1499   * @param snapshotName name of the snapshot to restore
1500   * @param takeFailSafeSnapshot <code>true</code> if the failsafe snapshot should be taken
1501   * @throws IOException if a remote or network exception occurs
1502   * @throws RestoreSnapshotException if snapshot failed to be restored
1503   * @throws IllegalArgumentException if the restore request is formatted incorrectly
1504   */
1505  default void restoreSnapshot(String snapshotName, boolean takeFailSafeSnapshot)
1506      throws IOException, RestoreSnapshotException {
1507    restoreSnapshot(snapshotName, takeFailSafeSnapshot, false);
1508  }
1509
1510  /**
1511   * Restore the specified snapshot on the original table. (The table must be disabled) If
1512   * 'takeFailSafeSnapshot' is set to <code>true</code>, a snapshot of the current table is taken
1513   * before executing the restore operation. In case of restore failure, the failsafe snapshot will
1514   * be restored. If the restore completes without problem the failsafe snapshot is deleted. The
1515   * failsafe snapshot name is configurable by using the property
1516   * "hbase.snapshot.restore.failsafe.name".
1517   * @param snapshotName name of the snapshot to restore
1518   * @param takeFailSafeSnapshot <code>true</code> if the failsafe snapshot should be taken
1519   * @param restoreAcl <code>true</code> to restore acl of snapshot
1520   * @throws IOException if a remote or network exception occurs
1521   * @throws RestoreSnapshotException if snapshot failed to be restored
1522   * @throws IllegalArgumentException if the restore request is formatted incorrectly
1523   */
1524  void restoreSnapshot(String snapshotName, boolean takeFailSafeSnapshot, boolean restoreAcl)
1525      throws IOException, RestoreSnapshotException;
1526
1527  /**
1528   * Create a new table by cloning the snapshot content.
1529   * @param snapshotName name of the snapshot to be cloned
1530   * @param tableName name of the table where the snapshot will be restored
1531   * @throws IOException if a remote or network exception occurs
1532   * @throws TableExistsException if table to be created already exists
1533   * @throws RestoreSnapshotException if snapshot failed to be cloned
1534   * @throws IllegalArgumentException if the specified table has not a valid name
1535   */
1536  default void cloneSnapshot(String snapshotName, TableName tableName)
1537      throws IOException, TableExistsException, RestoreSnapshotException {
1538    cloneSnapshot(snapshotName, tableName, false);
1539  }
1540
1541  /**
1542   * Create a new table by cloning the snapshot content.
1543   * @param snapshotName name of the snapshot to be cloned
1544   * @param tableName name of the table where the snapshot will be restored
1545   * @param restoreAcl <code>true</code> to clone acl into newly created table
1546   * @throws IOException if a remote or network exception occurs
1547   * @throws TableExistsException if table to be created already exists
1548   * @throws RestoreSnapshotException if snapshot failed to be cloned
1549   * @throws IllegalArgumentException if the specified table has not a valid name
1550   */
1551  default void cloneSnapshot(String snapshotName, TableName tableName, boolean restoreAcl)
1552      throws IOException, TableExistsException, RestoreSnapshotException {
1553    get(cloneSnapshotAsync(snapshotName, tableName, restoreAcl), getSyncWaitTimeout(),
1554      TimeUnit.MILLISECONDS);
1555  }
1556
1557  /**
1558   * Create a new table by cloning the snapshot content, but does not block and wait for it to be
1559   * completely cloned. You can use Future.get(long, TimeUnit) to wait on the operation to complete.
1560   * It may throw ExecutionException if there was an error while executing the operation or
1561   * TimeoutException in case the wait timeout was not long enough to allow the operation to
1562   * complete.
1563   * @param snapshotName name of the snapshot to be cloned
1564   * @param tableName name of the table where the snapshot will be restored
1565   * @throws IOException if a remote or network exception occurs
1566   * @throws TableExistsException if table to be cloned already exists
1567   * @return the result of the async clone snapshot. You can use Future.get(long, TimeUnit) to wait
1568   *         on the operation to complete.
1569   */
1570  default Future<Void> cloneSnapshotAsync(String snapshotName, TableName tableName)
1571      throws IOException, TableExistsException {
1572    return cloneSnapshotAsync(snapshotName, tableName, false);
1573  }
1574
1575  /**
1576   * Create a new table by cloning the snapshot content.
1577   * @param snapshotName name of the snapshot to be cloned
1578   * @param tableName name of the table where the snapshot will be restored
1579   * @param restoreAcl <code>true</code> to clone acl into newly created table
1580   * @throws IOException if a remote or network exception occurs
1581   * @throws TableExistsException if table to be created already exists
1582   * @throws RestoreSnapshotException if snapshot failed to be cloned
1583   * @throws IllegalArgumentException if the specified table has not a valid name
1584   */
1585  Future<Void> cloneSnapshotAsync(String snapshotName, TableName tableName, boolean restoreAcl)
1586      throws IOException, TableExistsException, RestoreSnapshotException;
1587
1588  /**
1589   * Execute a distributed procedure on a cluster.
1590   *
1591   * @param signature A distributed procedure is uniquely identified by its signature (default the
1592   * root ZK node name of the procedure).
1593   * @param instance The instance name of the procedure. For some procedures, this parameter is
1594   * optional.
1595   * @param props Property/Value pairs of properties passing to the procedure
1596   * @throws IOException if a remote or network exception occurs
1597   */
1598  void execProcedure(String signature, String instance, Map<String, String> props)
1599      throws IOException;
1600
1601  /**
1602   * Execute a distributed procedure on a cluster.
1603   *
1604   * @param signature A distributed procedure is uniquely identified by its signature (default the
1605   * root ZK node name of the procedure).
1606   * @param instance The instance name of the procedure. For some procedures, this parameter is
1607   * optional.
1608   * @param props Property/Value pairs of properties passing to the procedure
1609   * @return data returned after procedure execution. null if no return data.
1610   * @throws IOException if a remote or network exception occurs
1611   */
1612  byte[] execProcedureWithReturn(String signature, String instance, Map<String, String> props)
1613      throws IOException;
1614
1615  /**
1616   * Check the current state of the specified procedure. There are three possible states: <ol>
1617   * <li>running - returns <tt>false</tt></li> <li>finished - returns <tt>true</tt></li>
1618   * <li>finished with error - throws the exception that caused the procedure to fail</li> </ol>
1619   *
1620   * @param signature The signature that uniquely identifies a procedure
1621   * @param instance The instance name of the procedure
1622   * @param props Property/Value pairs of properties passing to the procedure
1623   * @return <code>true</code> if the specified procedure is finished successfully, <code>false</code> if it is still running
1624   * @throws IOException if the specified procedure finished with error
1625   */
1626  boolean isProcedureFinished(String signature, String instance, Map<String, String> props)
1627      throws IOException;
1628
1629  /**
1630   * List completed snapshots.
1631   *
1632   * @return a list of snapshot descriptors for completed snapshots
1633   * @throws IOException if a network error occurs
1634   */
1635  List<SnapshotDescription> listSnapshots() throws IOException;
1636
1637  /**
1638   * List all the completed snapshots matching the given pattern.
1639   *
1640   * @param pattern The compiled regular expression to match against
1641   * @return list of SnapshotDescription
1642   * @throws IOException if a remote or network exception occurs
1643   */
1644  List<SnapshotDescription> listSnapshots(Pattern pattern) throws IOException;
1645
1646  /**
1647   * List all the completed snapshots matching the given table name regular expression and snapshot
1648   * name regular expression.
1649   * @param tableNamePattern The compiled table name regular expression to match against
1650   * @param snapshotNamePattern The compiled snapshot name regular expression to match against
1651   * @return list of completed SnapshotDescription
1652   * @throws IOException if a remote or network exception occurs
1653   */
1654  List<SnapshotDescription> listTableSnapshots(Pattern tableNamePattern,
1655      Pattern snapshotNamePattern) throws IOException;
1656
1657  /**
1658   * Delete an existing snapshot.
1659   *
1660   * @param snapshotName name of the snapshot
1661   * @throws IOException if a remote or network exception occurs
1662   */
1663  void deleteSnapshot(String snapshotName) throws IOException;
1664
1665  /**
1666   * Delete existing snapshots whose names match the pattern passed.
1667   *
1668   * @param pattern pattern for names of the snapshot to match
1669   * @throws IOException if a remote or network exception occurs
1670   */
1671  void deleteSnapshots(Pattern pattern) throws IOException;
1672
1673  /**
1674   * Delete all existing snapshots matching the given table name regular expression and snapshot
1675   * name regular expression.
1676   * @param tableNamePattern The compiled table name regular expression to match against
1677   * @param snapshotNamePattern The compiled snapshot name regular expression to match against
1678   * @throws IOException if a remote or network exception occurs
1679   */
1680  void deleteTableSnapshots(Pattern tableNamePattern, Pattern snapshotNamePattern)
1681      throws IOException;
1682
1683  /**
1684   * Apply the new quota settings.
1685   *
1686   * @param quota the quota settings
1687   * @throws IOException if a remote or network exception occurs
1688   */
1689  void setQuota(QuotaSettings quota) throws IOException;
1690
1691  /**
1692   * List the quotas based on the filter.
1693   * @param filter the quota settings filter
1694   * @return the QuotaSetting list
1695   * @throws IOException if a remote or network exception occurs
1696   */
1697  List<QuotaSettings> getQuota(QuotaFilter filter) throws IOException;
1698
1699  /**
1700   * Creates and returns a {@link com.google.protobuf.RpcChannel} instance connected to the active
1701   * master. <p> The obtained {@link com.google.protobuf.RpcChannel} instance can be used to access
1702   * a published coprocessor {@link com.google.protobuf.Service} using standard protobuf service
1703   * invocations: </p> <div style="background-color: #cccccc; padding: 2px">
1704   * <blockquote><pre>
1705   * CoprocessorRpcChannel channel = myAdmin.coprocessorService();
1706   * MyService.BlockingInterface service = MyService.newBlockingStub(channel);
1707   * MyCallRequest request = MyCallRequest.newBuilder()
1708   *     ...
1709   *     .build();
1710   * MyCallResponse response = service.myCall(null, request);
1711   * </pre></blockquote></div>
1712   *
1713   * @return A MasterCoprocessorRpcChannel instance
1714   * @deprecated since 3.0.0, will removed in 4.0.0. This is too low level, please stop using it any
1715   *             more. Use the coprocessorService methods in {@link AsyncAdmin} instead.
1716   */
1717  @Deprecated
1718  CoprocessorRpcChannel coprocessorService();
1719
1720
1721  /**
1722   * Creates and returns a {@link com.google.protobuf.RpcChannel} instance
1723   * connected to the passed region server.
1724   *
1725   * <p>
1726   * The obtained {@link com.google.protobuf.RpcChannel} instance can be used to access a published
1727   * coprocessor {@link com.google.protobuf.Service} using standard protobuf service invocations:
1728   * </p>
1729   *
1730   * <div style="background-color: #cccccc; padding: 2px">
1731   * <blockquote><pre>
1732   * CoprocessorRpcChannel channel = myAdmin.coprocessorService(serverName);
1733   * MyService.BlockingInterface service = MyService.newBlockingStub(channel);
1734   * MyCallRequest request = MyCallRequest.newBuilder()
1735   *     ...
1736   *     .build();
1737   * MyCallResponse response = service.myCall(null, request);
1738   * </pre></blockquote></div>
1739   *
1740   * @param serverName the server name to which the endpoint call is made
1741   * @return A RegionServerCoprocessorRpcChannel instance
1742   * @deprecated since 3.0.0, will removed in 4.0.0. This is too low level, please stop using it any
1743   *             more. Use the coprocessorService methods in {@link AsyncAdmin} instead.
1744   */
1745  @Deprecated
1746  CoprocessorRpcChannel coprocessorService(ServerName serverName);
1747
1748
1749  /**
1750   * Update the configuration and trigger an online config change
1751   * on the regionserver.
1752   * @param server : The server whose config needs to be updated.
1753   * @throws IOException if a remote or network exception occurs
1754   */
1755  void updateConfiguration(ServerName server) throws IOException;
1756
1757  /**
1758   * Update the configuration and trigger an online config change
1759   * on all the regionservers.
1760   * @throws IOException if a remote or network exception occurs
1761   */
1762  void updateConfiguration() throws IOException;
1763
1764  /**
1765   * Get the info port of the current master if one is available.
1766   * @return master info port
1767   * @throws IOException if a remote or network exception occurs
1768   */
1769  default int getMasterInfoPort() throws IOException {
1770    return getClusterMetrics(EnumSet.of(Option.MASTER_INFO_PORT)).getMasterInfoPort();
1771  }
1772
1773  /**
1774   * Return the set of supported security capabilities.
1775   * @throws IOException if a remote or network exception occurs
1776   * @throws UnsupportedOperationException
1777   */
1778  List<SecurityCapability> getSecurityCapabilities() throws IOException;
1779
1780  /**
1781   * Turn the split switch on or off.
1782   * @param enabled enabled or not
1783   * @param synchronous If <code>true</code>, it waits until current split() call, if outstanding,
1784   *          to return.
1785   * @return Previous switch value
1786   * @throws IOException if a remote or network exception occurs
1787   */
1788  boolean splitSwitch(boolean enabled, boolean synchronous) throws IOException;
1789
1790  /**
1791   * Turn the merge switch on or off.
1792   * @param enabled enabled or not
1793   * @param synchronous If <code>true</code>, it waits until current merge() call, if outstanding,
1794   *          to return.
1795   * @return Previous switch value
1796   * @throws IOException if a remote or network exception occurs
1797   */
1798  boolean mergeSwitch(boolean enabled, boolean synchronous) throws IOException;
1799
1800  /**
1801   * Query the current state of the split switch.
1802   * @return <code>true</code> if the switch is enabled, <code>false</code> otherwise.
1803   * @throws IOException if a remote or network exception occurs
1804   */
1805  boolean isSplitEnabled() throws IOException;
1806
1807  /**
1808   * Query the current state of the merge switch.
1809   * @return <code>true</code> if the switch is enabled, <code>false</code> otherwise.
1810   * @throws IOException if a remote or network exception occurs
1811   */
1812  boolean isMergeEnabled() throws IOException;
1813
1814  /**
1815   * Add a new replication peer for replicating data to slave cluster.
1816   * @param peerId a short name that identifies the peer
1817   * @param peerConfig configuration for the replication peer
1818   * @throws IOException if a remote or network exception occurs
1819   */
1820  default void addReplicationPeer(String peerId, ReplicationPeerConfig peerConfig)
1821      throws IOException {
1822    addReplicationPeer(peerId, peerConfig, true);
1823  }
1824
1825  /**
1826   * Add a new replication peer for replicating data to slave cluster.
1827   * @param peerId a short name that identifies the peer
1828   * @param peerConfig configuration for the replication peer
1829   * @param enabled peer state, true if ENABLED and false if DISABLED
1830   * @throws IOException if a remote or network exception occurs
1831   */
1832  default void addReplicationPeer(String peerId, ReplicationPeerConfig peerConfig, boolean enabled)
1833      throws IOException {
1834    get(addReplicationPeerAsync(peerId, peerConfig, enabled), getSyncWaitTimeout(),
1835      TimeUnit.MILLISECONDS);
1836  }
1837
1838  /**
1839   * Add a new replication peer but does not block and wait for it.
1840   * <p/>
1841   * You can use Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
1842   * ExecutionException if there was an error while executing the operation or TimeoutException in
1843   * case the wait timeout was not long enough to allow the operation to complete.
1844   * @param peerId a short name that identifies the peer
1845   * @param peerConfig configuration for the replication peer
1846   * @return the result of the async operation
1847   * @throws IOException IOException if a remote or network exception occurs
1848   */
1849  default Future<Void> addReplicationPeerAsync(String peerId, ReplicationPeerConfig peerConfig)
1850      throws IOException {
1851    return addReplicationPeerAsync(peerId, peerConfig, true);
1852  }
1853
1854  /**
1855   * Add a new replication peer but does not block and wait for it.
1856   * <p>
1857   * You can use Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
1858   * ExecutionException if there was an error while executing the operation or TimeoutException in
1859   * case the wait timeout was not long enough to allow the operation to complete.
1860   * @param peerId a short name that identifies the peer
1861   * @param peerConfig configuration for the replication peer
1862   * @param enabled peer state, true if ENABLED and false if DISABLED
1863   * @return the result of the async operation
1864   * @throws IOException IOException if a remote or network exception occurs
1865   */
1866  Future<Void> addReplicationPeerAsync(String peerId, ReplicationPeerConfig peerConfig,
1867      boolean enabled) throws IOException;
1868
1869  /**
1870   * Remove a peer and stop the replication.
1871   * @param peerId a short name that identifies the peer
1872   * @throws IOException if a remote or network exception occurs
1873   */
1874  default void removeReplicationPeer(String peerId) throws IOException {
1875    get(removeReplicationPeerAsync(peerId), getSyncWaitTimeout(),
1876      TimeUnit.MILLISECONDS);
1877  }
1878
1879  /**
1880   * Remove a replication peer but does not block and wait for it.
1881   * <p>
1882   * You can use Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
1883   * ExecutionException if there was an error while executing the operation or TimeoutException in
1884   * case the wait timeout was not long enough to allow the operation to complete.
1885   * @param peerId a short name that identifies the peer
1886   * @return the result of the async operation
1887   * @throws IOException IOException if a remote or network exception occurs
1888   */
1889  Future<Void> removeReplicationPeerAsync(String peerId) throws IOException;
1890
1891  /**
1892   * Restart the replication stream to the specified peer.
1893   * @param peerId a short name that identifies the peer
1894   * @throws IOException if a remote or network exception occurs
1895   */
1896  default void enableReplicationPeer(String peerId) throws IOException {
1897    get(enableReplicationPeerAsync(peerId), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
1898  }
1899
1900  /**
1901   * Enable a replication peer but does not block and wait for it.
1902   * <p>
1903   * You can use Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
1904   * ExecutionException if there was an error while executing the operation or TimeoutException in
1905   * case the wait timeout was not long enough to allow the operation to complete.
1906   * @param peerId a short name that identifies the peer
1907   * @return the result of the async operation
1908   * @throws IOException IOException if a remote or network exception occurs
1909   */
1910  Future<Void> enableReplicationPeerAsync(String peerId) throws IOException;
1911
1912  /**
1913   * Stop the replication stream to the specified peer.
1914   * @param peerId a short name that identifies the peer
1915   * @throws IOException if a remote or network exception occurs
1916   */
1917  default void disableReplicationPeer(String peerId) throws IOException {
1918    get(disableReplicationPeerAsync(peerId), getSyncWaitTimeout(), TimeUnit.MILLISECONDS);
1919  }
1920
1921  /**
1922   * Disable a replication peer but does not block and wait for it.
1923   * <p/>
1924   * You can use Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
1925   * ExecutionException if there was an error while executing the operation or TimeoutException in
1926   * case the wait timeout was not long enough to allow the operation to complete.
1927   * @param peerId a short name that identifies the peer
1928   * @return the result of the async operation
1929   * @throws IOException IOException if a remote or network exception occurs
1930   */
1931  Future<Void> disableReplicationPeerAsync(String peerId) throws IOException;
1932
1933  /**
1934   * Returns the configured ReplicationPeerConfig for the specified peer.
1935   * @param peerId a short name that identifies the peer
1936   * @return ReplicationPeerConfig for the peer
1937   * @throws IOException if a remote or network exception occurs
1938   */
1939  ReplicationPeerConfig getReplicationPeerConfig(String peerId) throws IOException;
1940
1941  /**
1942   * Update the peerConfig for the specified peer.
1943   * @param peerId a short name that identifies the peer
1944   * @param peerConfig new config for the replication peer
1945   * @throws IOException if a remote or network exception occurs
1946   */
1947  default void updateReplicationPeerConfig(String peerId, ReplicationPeerConfig peerConfig)
1948      throws IOException {
1949    get(updateReplicationPeerConfigAsync(peerId, peerConfig), getSyncWaitTimeout(),
1950      TimeUnit.MILLISECONDS);
1951  }
1952
1953  /**
1954   * Update the peerConfig for the specified peer but does not block and wait for it.
1955   * <p/>
1956   * You can use Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
1957   * ExecutionException if there was an error while executing the operation or TimeoutException in
1958   * case the wait timeout was not long enough to allow the operation to complete.
1959   * @param peerId a short name that identifies the peer
1960   * @param peerConfig new config for the replication peer
1961   * @return the result of the async operation
1962   * @throws IOException IOException if a remote or network exception occurs
1963   */
1964  Future<Void> updateReplicationPeerConfigAsync(String peerId, ReplicationPeerConfig peerConfig)
1965      throws IOException;
1966
1967  /**
1968   * Append the replicable table column family config from the specified peer.
1969   * @param id a short that identifies the cluster
1970   * @param tableCfs A map from tableName to column family names
1971   * @throws ReplicationException if tableCfs has conflict with existing config
1972   * @throws IOException if a remote or network exception occurs
1973   */
1974  default void appendReplicationPeerTableCFs(String id, Map<TableName, List<String>> tableCfs)
1975      throws ReplicationException, IOException {
1976    if (tableCfs == null) {
1977      throw new ReplicationException("tableCfs is null");
1978    }
1979    ReplicationPeerConfig peerConfig = getReplicationPeerConfig(id);
1980    ReplicationPeerConfig newPeerConfig =
1981      ReplicationPeerConfigUtil.appendTableCFsToReplicationPeerConfig(tableCfs, peerConfig);
1982    updateReplicationPeerConfig(id, newPeerConfig);
1983  }
1984
1985  /**
1986   * Remove some table-cfs from config of the specified peer.
1987   * @param id a short name that identifies the cluster
1988   * @param tableCfs A map from tableName to column family names
1989   * @throws ReplicationException if tableCfs has conflict with existing config
1990   * @throws IOException if a remote or network exception occurs
1991   */
1992  default void removeReplicationPeerTableCFs(String id, Map<TableName, List<String>> tableCfs)
1993      throws ReplicationException, IOException {
1994    if (tableCfs == null) {
1995      throw new ReplicationException("tableCfs is null");
1996    }
1997    ReplicationPeerConfig peerConfig = getReplicationPeerConfig(id);
1998    ReplicationPeerConfig newPeerConfig =
1999      ReplicationPeerConfigUtil.removeTableCFsFromReplicationPeerConfig(tableCfs, peerConfig, id);
2000    updateReplicationPeerConfig(id, newPeerConfig);
2001  }
2002
2003  /**
2004   * Return a list of replication peers.
2005   * @return a list of replication peers description
2006   * @throws IOException if a remote or network exception occurs
2007   */
2008  List<ReplicationPeerDescription> listReplicationPeers() throws IOException;
2009
2010  /**
2011   * Return a list of replication peers.
2012   * @param pattern The compiled regular expression to match peer id
2013   * @return a list of replication peers description
2014   * @throws IOException if a remote or network exception occurs
2015   */
2016  List<ReplicationPeerDescription> listReplicationPeers(Pattern pattern) throws IOException;
2017
2018  /**
2019   * Transit current cluster to a new state in a synchronous replication peer.
2020   * @param peerId a short name that identifies the peer
2021   * @param state a new state of current cluster
2022   * @throws IOException if a remote or network exception occurs
2023   */
2024  default void transitReplicationPeerSyncReplicationState(String peerId, SyncReplicationState state)
2025      throws IOException {
2026    get(transitReplicationPeerSyncReplicationStateAsync(peerId, state), getSyncWaitTimeout(),
2027      TimeUnit.MILLISECONDS);
2028  }
2029
2030  /**
2031   * Transit current cluster to a new state in a synchronous replication peer. But does not block
2032   * and wait for it.
2033   * <p>
2034   * You can use Future.get(long, TimeUnit) to wait on the operation to complete. It may throw
2035   * ExecutionException if there was an error while executing the operation or TimeoutException in
2036   * case the wait timeout was not long enough to allow the operation to complete.
2037   * @param peerId a short name that identifies the peer
2038   * @param state a new state of current cluster
2039   * @throws IOException if a remote or network exception occurs
2040   */
2041  Future<Void> transitReplicationPeerSyncReplicationStateAsync(String peerId,
2042      SyncReplicationState state) throws IOException;
2043
2044  /**
2045   * Get the current cluster state in a synchronous replication peer.
2046   * @param peerId a short name that identifies the peer
2047   * @return the current cluster state
2048   * @throws IOException if a remote or network exception occurs
2049   */
2050  default SyncReplicationState getReplicationPeerSyncReplicationState(String peerId)
2051      throws IOException {
2052    List<ReplicationPeerDescription> peers = listReplicationPeers(Pattern.compile(peerId));
2053    if (peers.isEmpty() || !peers.get(0).getPeerId().equals(peerId)) {
2054      throw new IOException("Replication peer " + peerId + " does not exist");
2055    }
2056    return peers.get(0).getSyncReplicationState();
2057  }
2058
2059  /**
2060   * Mark region server(s) as decommissioned to prevent additional regions from getting
2061   * assigned to them. Optionally unload the regions on the servers. If there are multiple servers
2062   * to be decommissioned, decommissioning them at the same time can prevent wasteful region
2063   * movements. Region unloading is asynchronous.
2064   * @param servers The list of servers to decommission.
2065   * @param offload True to offload the regions from the decommissioned servers
2066   * @throws IOException if a remote or network exception occurs
2067   */
2068  void decommissionRegionServers(List<ServerName> servers, boolean offload) throws IOException;
2069
2070  /**
2071   * List region servers marked as decommissioned, which can not be assigned regions.
2072   * @return List of decommissioned region servers.
2073   * @throws IOException if a remote or network exception occurs
2074   */
2075  List<ServerName> listDecommissionedRegionServers() throws IOException;
2076
2077  /**
2078   * Remove decommission marker from a region server to allow regions assignments.
2079   * Load regions onto the server if a list of regions is given. Region loading is
2080   * asynchronous.
2081   * @param server The server to recommission.
2082   * @param encodedRegionNames Regions to load onto the server.
2083   * @throws IOException if a remote or network exception occurs
2084   */
2085  void recommissionRegionServer(ServerName server, List<byte[]> encodedRegionNames)
2086      throws IOException;
2087
2088  /**
2089   * Find all table and column families that are replicated from this cluster
2090   * @return the replicated table-cfs list of this cluster.
2091   * @throws IOException if a remote or network exception occurs
2092   */
2093  List<TableCFs> listReplicatedTableCFs() throws IOException;
2094
2095  /**
2096   * Enable a table's replication switch.
2097   * @param tableName name of the table
2098   * @throws IOException if a remote or network exception occurs
2099   */
2100  void enableTableReplication(TableName tableName) throws IOException;
2101
2102  /**
2103   * Disable a table's replication switch.
2104   * @param tableName name of the table
2105   * @throws IOException if a remote or network exception occurs
2106   */
2107  void disableTableReplication(TableName tableName) throws IOException;
2108
2109  /**
2110   * Clear compacting queues on a regionserver.
2111   * @param serverName the region server name
2112   * @param queues the set of queue name
2113   * @throws IOException if a remote or network exception occurs
2114   * @throws InterruptedException
2115   */
2116  void clearCompactionQueues(ServerName serverName, Set<String> queues)
2117    throws IOException, InterruptedException;
2118
2119  /**
2120   * List dead region servers.
2121   * @return List of dead region servers.
2122   */
2123  default List<ServerName> listDeadServers() throws IOException {
2124    return getClusterMetrics(EnumSet.of(Option.DEAD_SERVERS)).getDeadServerNames();
2125  }
2126
2127  /**
2128   * Clear dead region servers from master.
2129   * @param servers list of dead region servers.
2130   * @throws IOException if a remote or network exception occurs
2131   * @return List of servers that are not cleared
2132   */
2133  List<ServerName> clearDeadServers(List<ServerName> servers) throws IOException;
2134
2135  /**
2136   * Create a new table by cloning the existent table schema.
2137   * @param tableName name of the table to be cloned
2138   * @param newTableName name of the new table where the table will be created
2139   * @param preserveSplits True if the splits should be preserved
2140   * @throws IOException if a remote or network exception occurs
2141   */
2142  void cloneTableSchema(TableName tableName, TableName newTableName, boolean preserveSplits)
2143      throws IOException;
2144
2145  /**
2146   * Switch the rpc throttle enable state.
2147   * @param enable Set to <code>true</code> to enable, <code>false</code> to disable.
2148   * @return Previous rpc throttle enabled value
2149   * @throws IOException if a remote or network exception occurs
2150   */
2151  boolean switchRpcThrottle(boolean enable) throws IOException;
2152
2153  /**
2154   * Get if the rpc throttle is enabled.
2155   * @return True if rpc throttle is enabled
2156   * @throws IOException if a remote or network exception occurs
2157   */
2158  boolean isRpcThrottleEnabled() throws IOException;
2159
2160  /**
2161   * Switch the exceed throttle quota. If enabled, user/table/namespace throttle quota
2162   * can be exceeded if region server has availble quota.
2163   * @param enable Set to <code>true</code> to enable, <code>false</code> to disable.
2164   * @return Previous exceed throttle enabled value
2165   * @throws IOException if a remote or network exception occurs
2166   */
2167  boolean exceedThrottleQuotaSwitch(final boolean enable) throws IOException;
2168
2169  /**
2170   * Fetches the table sizes on the filesystem as tracked by the HBase Master.
2171   * @throws IOException if a remote or network exception occurs
2172   */
2173  Map<TableName, Long> getSpaceQuotaTableSizes() throws IOException;
2174
2175  /**
2176   * Fetches the observed {@link SpaceQuotaSnapshotView}s observed by a RegionServer.
2177   * @throws IOException if a remote or network exception occurs
2178   */
2179  Map<TableName, ? extends SpaceQuotaSnapshotView> getRegionServerSpaceQuotaSnapshots(
2180      ServerName serverName) throws IOException;
2181
2182  /**
2183   * Returns the Master's view of a quota on the given {@code namespace} or null if the Master has
2184   * no quota information on that namespace.
2185   * @throws IOException if a remote or network exception occurs
2186   */
2187  SpaceQuotaSnapshotView getCurrentSpaceQuotaSnapshot(String namespace) throws IOException;
2188
2189  /**
2190   * Returns the Master's view of a quota on the given {@code tableName} or null if the Master has
2191   * no quota information on that table.
2192   * @throws IOException if a remote or network exception occurs
2193   */
2194  SpaceQuotaSnapshotView getCurrentSpaceQuotaSnapshot(TableName tableName) throws IOException;
2195
2196  /**
2197   * Grants user specific permissions
2198   * @param userPermission user name and the specific permission
2199   * @param mergeExistingPermissions If set to false, later granted permissions will override
2200   *          previous granted permissions. otherwise, it'll merge with previous granted
2201   *          permissions.
2202   * @throws IOException if a remote or network exception occurs
2203   */
2204  void grant(UserPermission userPermission, boolean mergeExistingPermissions) throws IOException;
2205
2206  /**
2207   * Revokes user specific permissions
2208   * @param userPermission user name and the specific permission
2209   * @throws IOException if a remote or network exception occurs
2210   */
2211  void revoke(UserPermission userPermission) throws IOException;
2212
2213  /**
2214   * Get the global/namespace/table permissions for user
2215   * @param getUserPermissionsRequest A request contains which user, global, namespace or table
2216   *          permissions needed
2217   * @return The user and permission list
2218   * @throws IOException if a remote or network exception occurs
2219   */
2220  List<UserPermission> getUserPermissions(GetUserPermissionsRequest getUserPermissionsRequest)
2221      throws IOException;
2222
2223  /**
2224   * Check if the user has specific permissions
2225   * @param userName the user name
2226   * @param permissions the specific permission list
2227   * @return True if user has the specific permissions
2228   * @throws IOException if a remote or network exception occurs
2229   */
2230  List<Boolean> hasUserPermissions(String userName, List<Permission> permissions)
2231      throws IOException;
2232
2233  /**
2234   * Check if call user has specific permissions
2235   * @param permissions the specific permission list
2236   * @return True if user has the specific permissions
2237   * @throws IOException if a remote or network exception occurs
2238   */
2239  default List<Boolean> hasUserPermissions(List<Permission> permissions) throws IOException {
2240    return hasUserPermissions(null, permissions);
2241  }
2242
2243  /**
2244   * Turn on or off the auto snapshot cleanup based on TTL.
2245   *
2246   * @param on Set to <code>true</code> to enable, <code>false</code> to disable.
2247   * @param synchronous If <code>true</code>, it waits until current snapshot cleanup is completed,
2248   *   if outstanding.
2249   * @return Previous auto snapshot cleanup value
2250   * @throws IOException if a remote or network exception occurs
2251   */
2252  boolean snapshotCleanupSwitch(final boolean on, final boolean synchronous)
2253      throws IOException;
2254
2255  /**
2256   * Query the current state of the auto snapshot cleanup based on TTL.
2257   *
2258   * @return <code>true</code> if the auto snapshot cleanup is enabled,
2259   *   <code>false</code> otherwise.
2260   * @throws IOException if a remote or network exception occurs
2261   */
2262  boolean isSnapshotCleanupEnabled() throws IOException;
2263
2264}