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 com.google.protobuf.RpcChannel;
021import java.util.Arrays;
022import java.util.Collection;
023import java.util.EnumSet;
024import java.util.HashMap;
025import java.util.List;
026import java.util.Map;
027import java.util.Optional;
028import java.util.Set;
029import java.util.concurrent.CompletableFuture;
030import java.util.function.Function;
031import java.util.regex.Pattern;
032import java.util.stream.Collectors;
033import org.apache.hadoop.hbase.CacheEvictionStats;
034import org.apache.hadoop.hbase.ClusterMetrics;
035import org.apache.hadoop.hbase.ClusterMetrics.Option;
036import org.apache.hadoop.hbase.NamespaceDescriptor;
037import org.apache.hadoop.hbase.RegionMetrics;
038import org.apache.hadoop.hbase.ServerName;
039import org.apache.hadoop.hbase.TableName;
040import org.apache.hadoop.hbase.client.replication.TableCFs;
041import org.apache.hadoop.hbase.client.security.SecurityCapability;
042import org.apache.hadoop.hbase.quotas.QuotaFilter;
043import org.apache.hadoop.hbase.quotas.QuotaSettings;
044import org.apache.hadoop.hbase.quotas.SpaceQuotaSnapshotView;
045import org.apache.hadoop.hbase.replication.ReplicationPeerConfig;
046import org.apache.hadoop.hbase.replication.ReplicationPeerDescription;
047import org.apache.hadoop.hbase.security.access.GetUserPermissionsRequest;
048import org.apache.hadoop.hbase.security.access.Permission;
049import org.apache.hadoop.hbase.security.access.UserPermission;
050import org.apache.yetus.audience.InterfaceAudience;
051
052/**
053 * The asynchronous administrative API for HBase.
054 * @since 2.0.0
055 */
056@InterfaceAudience.Public
057public interface AsyncAdmin {
058
059  /**
060   * @param tableName Table to check.
061   * @return True if table exists already. The return value will be wrapped by a
062   *         {@link CompletableFuture}.
063   */
064  CompletableFuture<Boolean> tableExists(TableName tableName);
065
066  /**
067   * List all the userspace tables.
068   * @return - returns a list of TableDescriptors wrapped by a {@link CompletableFuture}.
069   */
070  default CompletableFuture<List<TableDescriptor>> listTableDescriptors() {
071    return listTableDescriptors(false);
072  }
073
074  /**
075   * List all the tables.
076   * @param includeSysTables False to match only against userspace tables
077   * @return - returns a list of TableDescriptors wrapped by a {@link CompletableFuture}.
078   */
079  CompletableFuture<List<TableDescriptor>> listTableDescriptors(boolean includeSysTables);
080
081  /**
082   * List all the tables matching the given pattern.
083   * @param pattern The compiled regular expression to match against
084   * @param includeSysTables False to match only against userspace tables
085   * @return - returns a list of TableDescriptors wrapped by a {@link CompletableFuture}.
086   */
087  CompletableFuture<List<TableDescriptor>> listTableDescriptors(Pattern pattern,
088      boolean includeSysTables);
089
090  /**
091   * List specific tables including system tables.
092   * @param tableNames the table list to match against
093   * @return - returns a list of TableDescriptors wrapped by a {@link CompletableFuture}.
094   */
095  CompletableFuture<List<TableDescriptor>> listTableDescriptors(List<TableName> tableNames);
096
097  /**
098   * Get list of table descriptors by namespace.
099   * @param name namespace name
100   * @return returns a list of TableDescriptors wrapped by a {@link CompletableFuture}.
101   */
102  CompletableFuture<List<TableDescriptor>> listTableDescriptorsByNamespace(String name);
103
104  /**
105   * List all of the names of userspace tables.
106   * @return a list of table names wrapped by a {@link CompletableFuture}.
107   * @see #listTableNames(Pattern, boolean)
108   */
109  default CompletableFuture<List<TableName>> listTableNames() {
110    return listTableNames(false);
111  }
112
113  /**
114   * List all of the names of tables.
115   * @param includeSysTables False to match only against userspace tables
116   * @return a list of table names wrapped by a {@link CompletableFuture}.
117   */
118  CompletableFuture<List<TableName>> listTableNames(boolean includeSysTables);
119
120  /**
121   * List all of the names of userspace tables.
122   * @param pattern The regular expression to match against
123   * @param includeSysTables False to match only against userspace tables
124   * @return a list of table names wrapped by a {@link CompletableFuture}.
125   */
126  CompletableFuture<List<TableName>> listTableNames(Pattern pattern, boolean includeSysTables);
127
128  /**
129   * Get list of table names by namespace.
130   * @param name namespace name
131   * @return The list of table names in the namespace wrapped by a {@link CompletableFuture}.
132   */
133  CompletableFuture<List<TableName>> listTableNamesByNamespace(String name);
134
135  /**
136   * Method for getting the tableDescriptor
137   * @param tableName as a {@link TableName}
138   * @return the read-only tableDescriptor wrapped by a {@link CompletableFuture}.
139   */
140  CompletableFuture<TableDescriptor> getDescriptor(TableName tableName);
141
142  /**
143   * Creates a new table.
144   * @param desc table descriptor for table
145   */
146  CompletableFuture<Void> createTable(TableDescriptor desc);
147
148  /**
149   * Creates a new table with the specified number of regions. The start key specified will become
150   * the end key of the first region of the table, and the end key specified will become the start
151   * key of the last region of the table (the first region has a null start key and the last region
152   * has a null end key). BigInteger math will be used to divide the key range specified into enough
153   * segments to make the required number of total regions.
154   * @param desc table descriptor for table
155   * @param startKey beginning of key range
156   * @param endKey end of key range
157   * @param numRegions the total number of regions to create
158   */
159  CompletableFuture<Void> createTable(TableDescriptor desc, byte[] startKey, byte[] endKey,
160      int numRegions);
161
162  /**
163   * Creates a new table with an initial set of empty regions defined by the specified split keys.
164   * The total number of regions created will be the number of split keys plus one.
165   * Note : Avoid passing empty split key.
166   * @param desc table descriptor for table
167   * @param splitKeys array of split keys for the initial regions of the table
168   */
169  CompletableFuture<Void> createTable(TableDescriptor desc, byte[][] splitKeys);
170
171  /**
172   * Modify an existing table, more IRB friendly version.
173   * @param desc modified description of the table
174   */
175  CompletableFuture<Void> modifyTable(TableDescriptor desc);
176
177  /**
178   * Deletes a table.
179   * @param tableName name of table to delete
180   */
181  CompletableFuture<Void> deleteTable(TableName tableName);
182
183  /**
184   * Truncate a table.
185   * @param tableName name of table to truncate
186   * @param preserveSplits True if the splits should be preserved
187   */
188  CompletableFuture<Void> truncateTable(TableName tableName, boolean preserveSplits);
189
190  /**
191   * Enable a table. The table has to be in disabled state for it to be enabled.
192   * @param tableName name of the table
193   */
194  CompletableFuture<Void> enableTable(TableName tableName);
195
196  /**
197   * Disable a table. The table has to be in enabled state for it to be disabled.
198   * @param tableName
199   */
200  CompletableFuture<Void> disableTable(TableName tableName);
201
202  /**
203   * @param tableName name of table to check
204   * @return true if table is on-line. The return value will be wrapped by a
205   *         {@link CompletableFuture}.
206   */
207  CompletableFuture<Boolean> isTableEnabled(TableName tableName);
208
209  /**
210   * @param tableName name of table to check
211   * @return true if table is off-line. The return value will be wrapped by a
212   *         {@link CompletableFuture}.
213   */
214  CompletableFuture<Boolean> isTableDisabled(TableName tableName);
215
216  /**
217   * @param tableName name of table to check
218   * @return true if all regions of the table are available. The return value will be wrapped by a
219   *         {@link CompletableFuture}.
220   */
221  CompletableFuture<Boolean> isTableAvailable(TableName tableName);
222
223  /**
224   * Use this api to check if the table has been created with the specified number of splitkeys
225   * which was used while creating the given table. Note : If this api is used after a table's
226   * region gets splitted, the api may return false. The return value will be wrapped by a
227   * {@link CompletableFuture}.
228   * @param tableName name of table to check
229   * @param splitKeys keys to check if the table has been created with all split keys
230   * @deprecated Since 2.2.0. Will be removed in 3.0.0. Use {@link #isTableAvailable(TableName)}
231   */
232  @Deprecated
233  CompletableFuture<Boolean> isTableAvailable(TableName tableName, byte[][] splitKeys);
234
235  /**
236   * Add a column family to an existing table.
237   * @param tableName name of the table to add column family to
238   * @param columnFamily column family descriptor of column family to be added
239   */
240  CompletableFuture<Void> addColumnFamily(TableName tableName,
241      ColumnFamilyDescriptor columnFamily);
242
243  /**
244   * Delete a column family from a table.
245   * @param tableName name of table
246   * @param columnFamily name of column family to be deleted
247   */
248  CompletableFuture<Void> deleteColumnFamily(TableName tableName, byte[] columnFamily);
249
250  /**
251   * Modify an existing column family on a table.
252   * @param tableName name of table
253   * @param columnFamily new column family descriptor to use
254   */
255  CompletableFuture<Void> modifyColumnFamily(TableName tableName,
256      ColumnFamilyDescriptor columnFamily);
257
258  /**
259   * Create a new namespace.
260   * @param descriptor descriptor which describes the new namespace
261   */
262  CompletableFuture<Void> createNamespace(NamespaceDescriptor descriptor);
263
264  /**
265   * Modify an existing namespace.
266   * @param descriptor descriptor which describes the new namespace
267   */
268  CompletableFuture<Void> modifyNamespace(NamespaceDescriptor descriptor);
269
270  /**
271   * Delete an existing namespace. Only empty namespaces (no tables) can be removed.
272   * @param name namespace name
273   */
274  CompletableFuture<Void> deleteNamespace(String name);
275
276  /**
277   * Get a namespace descriptor by name
278   * @param name name of namespace descriptor
279   * @return A descriptor wrapped by a {@link CompletableFuture}.
280   */
281  CompletableFuture<NamespaceDescriptor> getNamespaceDescriptor(String name);
282
283  /**
284   * List available namespaces
285   * @return List of namespaces wrapped by a {@link CompletableFuture}.
286   */
287  CompletableFuture<List<String>> listNamespaces();
288
289  /**
290   * List available namespace descriptors
291   * @return List of descriptors wrapped by a {@link CompletableFuture}.
292   */
293  CompletableFuture<List<NamespaceDescriptor>> listNamespaceDescriptors();
294
295  /**
296   * Get all the online regions on a region server.
297   */
298  CompletableFuture<List<RegionInfo>> getRegions(ServerName serverName);
299
300  /**
301   * Get the regions of a given table.
302   */
303  CompletableFuture<List<RegionInfo>> getRegions(TableName tableName);
304
305  /**
306   * Flush a table.
307   * @param tableName table to flush
308   */
309  CompletableFuture<Void> flush(TableName tableName);
310
311  /**
312   * Flush the specified column family stores on all regions of the passed table.
313   * This runs as a synchronous operation.
314   * @param tableName table to flush
315   * @param columnFamily column family within a table
316   */
317  CompletableFuture<Void> flush(TableName tableName, byte[] columnFamily);
318
319  /**
320   * Flush an individual region.
321   * @param regionName region to flush
322   */
323  CompletableFuture<Void> flushRegion(byte[] regionName);
324
325  /**
326   * Flush a column family within a region.
327   * @param regionName region to flush
328   * @param columnFamily column family within a region. If not present, flush the region's all
329   *          column families.
330   */
331  CompletableFuture<Void> flushRegion(byte[] regionName, byte[] columnFamily);
332
333  /**
334   * Flush all region on the region server.
335   * @param serverName server to flush
336   */
337  CompletableFuture<Void> flushRegionServer(ServerName serverName);
338
339  /**
340   * Compact a table. When the returned CompletableFuture is done, it only means the compact request
341   * was sent to HBase and may need some time to finish the compact operation.
342   * Throws {@link org.apache.hadoop.hbase.TableNotFoundException} if table not found.
343   * @param tableName table to compact
344   */
345  default CompletableFuture<Void> compact(TableName tableName) {
346    return compact(tableName, CompactType.NORMAL);
347  }
348
349  /**
350   * Compact a column family within a table. When the returned CompletableFuture is done, it only
351   * means the compact request was sent to HBase and may need some time to finish the compact
352   * operation.
353   * Throws {@link org.apache.hadoop.hbase.TableNotFoundException} if table not found.
354   * @param tableName table to compact
355   * @param columnFamily column family within a table. If not present, compact the table's all
356   *          column families.
357   */
358  default CompletableFuture<Void> compact(TableName tableName, byte[] columnFamily) {
359    return compact(tableName, columnFamily, CompactType.NORMAL);
360  }
361
362  /**
363   * Compact a table. When the returned CompletableFuture is done, it only means the compact request
364   * was sent to HBase and may need some time to finish the compact operation.
365   * Throws {@link org.apache.hadoop.hbase.TableNotFoundException} if table not found for
366   * normal compaction type.
367   * @param tableName table to compact
368   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
369   */
370  CompletableFuture<Void> compact(TableName tableName, CompactType compactType);
371
372  /**
373   * Compact a column family within a table. When the returned CompletableFuture is done, it only
374   * means the compact request was sent to HBase and may need some time to finish the compact
375   * operation.
376   * Throws {@link org.apache.hadoop.hbase.TableNotFoundException} if table not found for
377   * normal compaction type.
378   * @param tableName table to compact
379   * @param columnFamily column family within a table
380   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
381   */
382  CompletableFuture<Void> compact(TableName tableName, byte[] columnFamily,
383      CompactType compactType);
384
385  /**
386   * Compact an individual region. When the returned CompletableFuture is done, it only means the
387   * compact request was sent to HBase and may need some time to finish the compact operation.
388   * @param regionName region to compact
389   */
390  CompletableFuture<Void> compactRegion(byte[] regionName);
391
392  /**
393   * Compact a column family within a region. When the returned CompletableFuture is done, it only
394   * means the compact request was sent to HBase and may need some time to finish the compact
395   * operation.
396   * @param regionName region to compact
397   * @param columnFamily column family within a region. If not present, compact the region's all
398   *          column families.
399   */
400  CompletableFuture<Void> compactRegion(byte[] regionName, byte[] columnFamily);
401
402  /**
403   * Major compact a table. When the returned CompletableFuture is done, it only means the compact
404   * request was sent to HBase and may need some time to finish the compact operation.
405   * Throws {@link org.apache.hadoop.hbase.TableNotFoundException} if table not found.
406   * @param tableName table to major compact
407   */
408  default CompletableFuture<Void> majorCompact(TableName tableName) {
409    return majorCompact(tableName, CompactType.NORMAL);
410  }
411
412  /**
413   * Major compact a column family within a table. When the returned CompletableFuture is done, it
414   * only means the compact request was sent to HBase and may need some time to finish the compact
415   * operation.
416   * Throws {@link org.apache.hadoop.hbase.TableNotFoundException} if table not found for
417   * normal compaction. type.
418   * @param tableName table to major compact
419   * @param columnFamily column family within a table. If not present, major compact the table's all
420   *          column families.
421   */
422  default CompletableFuture<Void> majorCompact(TableName tableName, byte[] columnFamily) {
423    return majorCompact(tableName, columnFamily, CompactType.NORMAL);
424  }
425
426  /**
427   * Major compact a table. When the returned CompletableFuture is done, it only means the compact
428   * request was sent to HBase and may need some time to finish the compact operation.
429   * Throws {@link org.apache.hadoop.hbase.TableNotFoundException} if table not found for
430   * normal compaction type.
431   * @param tableName table to major compact
432   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
433   */
434  CompletableFuture<Void> majorCompact(TableName tableName, CompactType compactType);
435
436  /**
437   * Major compact a column family within a table. When the returned CompletableFuture is done, it
438   * only means the compact request was sent to HBase and may need some time to finish the compact
439   * operation.
440   * Throws {@link org.apache.hadoop.hbase.TableNotFoundException} if table not found.
441   * @param tableName table to major compact
442   * @param columnFamily column family within a table. If not present, major compact the table's all
443   *          column families.
444   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
445   */
446  CompletableFuture<Void> majorCompact(TableName tableName, byte[] columnFamily,
447      CompactType compactType);
448
449  /**
450   * Major compact a region. When the returned CompletableFuture is done, it only means the compact
451   * request was sent to HBase and may need some time to finish the compact operation.
452   * @param regionName region to major compact
453   */
454  CompletableFuture<Void> majorCompactRegion(byte[] regionName);
455
456  /**
457   * Major compact a column family within region. When the returned CompletableFuture is done, it
458   * only means the compact request was sent to HBase and may need some time to finish the compact
459   * operation.
460   * @param regionName region to major compact
461   * @param columnFamily column family within a region. If not present, major compact the region's
462   *          all column families.
463   */
464  CompletableFuture<Void> majorCompactRegion(byte[] regionName, byte[] columnFamily);
465
466  /**
467   * Compact all regions on the region server.
468   * @param serverName the region server name
469   */
470  CompletableFuture<Void> compactRegionServer(ServerName serverName);
471
472  /**
473   * Compact all regions on the region server.
474   * @param serverName the region server name
475   */
476  CompletableFuture<Void> majorCompactRegionServer(ServerName serverName);
477
478  /**
479   * Turn the Merge switch on or off.
480   * @param enabled enabled or not
481   * @return Previous switch value wrapped by a {@link CompletableFuture}
482   */
483  default CompletableFuture<Boolean> mergeSwitch(boolean enabled) {
484    return mergeSwitch(enabled, false);
485  }
486
487  /**
488   * Turn the Merge switch on or off.
489   * <p/>
490   * Notice that, the method itself is always non-blocking, which means it will always return
491   * immediately. The {@code drainMerges} parameter only effects when will we complete the returned
492   * {@link CompletableFuture}.
493   * @param enabled enabled or not
494   * @param drainMerges If <code>true</code>, it waits until current merge() call, if outstanding,
495   *          to return.
496   * @return Previous switch value wrapped by a {@link CompletableFuture}
497   */
498  CompletableFuture<Boolean> mergeSwitch(boolean enabled, boolean drainMerges);
499
500  /**
501   * Query the current state of the Merge switch.
502   * @return true if the switch is on, false otherwise. The return value will be wrapped by a
503   *         {@link CompletableFuture}
504   */
505  CompletableFuture<Boolean> isMergeEnabled();
506
507  /**
508   * Turn the Split switch on or off.
509   * @param enabled enabled or not
510   * @return Previous switch value wrapped by a {@link CompletableFuture}
511   */
512  default CompletableFuture<Boolean> splitSwitch(boolean enabled) {
513    return splitSwitch(enabled, false);
514  }
515
516  /**
517   * Turn the Split switch on or off.
518   * <p/>
519   * Notice that, the method itself is always non-blocking, which means it will always return
520   * immediately. The {@code drainSplits} parameter only effects when will we complete the returned
521   * {@link CompletableFuture}.
522   * @param enabled enabled or not
523   * @param drainSplits If <code>true</code>, it waits until current split() call, if outstanding,
524   *          to return.
525   * @return Previous switch value wrapped by a {@link CompletableFuture}
526   */
527  CompletableFuture<Boolean> splitSwitch(boolean enabled, boolean drainSplits);
528
529  /**
530   * Query the current state of the Split switch.
531   * @return true if the switch is on, false otherwise. The return value will be wrapped by a
532   *         {@link CompletableFuture}
533   */
534  CompletableFuture<Boolean> isSplitEnabled();
535
536  /**
537   * Merge two regions.
538   * @param nameOfRegionA encoded or full name of region a
539   * @param nameOfRegionB encoded or full name of region b
540   * @param forcible true if do a compulsory merge, otherwise we will only merge two adjacent
541   *          regions
542   * @deprecated since 2.3.0 and will be removed in 4.0.0.Use {@link #mergeRegions(List, boolean)}
543   *             instead.
544   */
545  @Deprecated
546  default CompletableFuture<Void> mergeRegions(byte[] nameOfRegionA, byte[] nameOfRegionB,
547      boolean forcible) {
548    return mergeRegions(Arrays.asList(nameOfRegionA, nameOfRegionB), forcible);
549  }
550
551  /**
552   * Merge multiple regions (>=2).
553   * @param nameOfRegionsToMerge encoded or full name of daughter regions
554   * @param forcible true if do a compulsory merge, otherwise we will only merge two adjacent
555   *          regions
556   */
557  CompletableFuture<Void> mergeRegions(List<byte[]> nameOfRegionsToMerge, boolean forcible);
558
559  /**
560   * Split a table. The method will execute split action for each region in table.
561   * @param tableName table to split
562   */
563  CompletableFuture<Void> split(TableName tableName);
564
565  /**
566   * Split an individual region.
567   * @param regionName region to split
568   */
569  CompletableFuture<Void> splitRegion(byte[] regionName);
570
571  /**
572   * Split a table.
573   * @param tableName table to split
574   * @param splitPoint the explicit position to split on
575   */
576  CompletableFuture<Void> split(TableName tableName, byte[] splitPoint);
577
578  /**
579   * Split an individual region.
580   * @param regionName region to split
581   * @param splitPoint the explicit position to split on. If not present, it will decide by region
582   *          server.
583   */
584  CompletableFuture<Void> splitRegion(byte[] regionName, byte[] splitPoint);
585
586  /**
587   * @param regionName Encoded or full name of region to assign.
588   */
589  CompletableFuture<Void> assign(byte[] regionName);
590
591  /**
592   * @param regionName Encoded or full name of region to unassign.
593   */
594  CompletableFuture<Void> unassign(byte[] regionName);
595
596  /**
597   * Unassign a region from current hosting regionserver. Region will then be assigned to a
598   * regionserver chosen at random. Region could be reassigned back to the same server. Use
599   * {@link #move(byte[], ServerName)} if you want to control the region movement.
600   * @param regionName Encoded or full name of region to unassign. Will clear any existing
601   *          RegionPlan if one found.
602   * @param forcible If true, force unassign (Will remove region from regions-in-transition too if
603   *          present. If results in double assignment use hbck -fix to resolve. To be used by
604   *          experts).
605   * @deprecated since 2.4.0 and will be removed in 4.0.0. Use {@link #unassign(byte[])}
606   *   instead.
607   * @see <a href="https://issues.apache.org/jira/browse/HBASE-24875">HBASE-24875</a>
608   */
609  @Deprecated
610  default CompletableFuture<Void> unassign(byte[] regionName, boolean forcible) {
611    return unassign(regionName);
612  }
613
614  /**
615   * Offline specified region from master's in-memory state. It will not attempt to reassign the
616   * region as in unassign. This API can be used when a region not served by any region server and
617   * still online as per Master's in memory state. If this API is incorrectly used on active region
618   * then master will loose track of that region. This is a special method that should be used by
619   * experts or hbck.
620   * @param regionName Encoded or full name of region to offline
621   */
622  CompletableFuture<Void> offline(byte[] regionName);
623
624  /**
625   * Move the region <code>r</code> to a random server.
626   * @param regionName Encoded or full name of region to move.
627   */
628  CompletableFuture<Void> move(byte[] regionName);
629
630  /**
631   * Move the region <code>r</code> to <code>dest</code>.
632   * @param regionName Encoded or full name of region to move.
633   * @param destServerName The servername of the destination regionserver. If not present, we'll
634   *          assign to a random server. A server name is made of host, port and startcode. Here is
635   *          an example: <code> host187.example.com,60020,1289493121758</code>
636   */
637  CompletableFuture<Void> move(byte[] regionName, ServerName destServerName);
638
639  /**
640   * Apply the new quota settings.
641   * @param quota the quota settings
642   */
643  CompletableFuture<Void> setQuota(QuotaSettings quota);
644
645  /**
646   * List the quotas based on the filter.
647   * @param filter the quota settings filter
648   * @return the QuotaSetting list, which wrapped by a CompletableFuture.
649   */
650  CompletableFuture<List<QuotaSettings>> getQuota(QuotaFilter filter);
651
652  /**
653   * Add a new replication peer for replicating data to slave cluster
654   * @param peerId a short name that identifies the peer
655   * @param peerConfig configuration for the replication slave cluster
656   */
657  default CompletableFuture<Void> addReplicationPeer(String peerId,
658      ReplicationPeerConfig peerConfig) {
659    return addReplicationPeer(peerId, peerConfig, true);
660  }
661
662  /**
663   * Add a new replication peer for replicating data to slave cluster
664   * @param peerId a short name that identifies the peer
665   * @param peerConfig configuration for the replication slave cluster
666   * @param enabled peer state, true if ENABLED and false if DISABLED
667   */
668  CompletableFuture<Void> addReplicationPeer(String peerId,
669      ReplicationPeerConfig peerConfig, boolean enabled);
670
671  /**
672   * Remove a peer and stop the replication
673   * @param peerId a short name that identifies the peer
674   */
675  CompletableFuture<Void> removeReplicationPeer(String peerId);
676
677  /**
678   * Restart the replication stream to the specified peer
679   * @param peerId a short name that identifies the peer
680   */
681  CompletableFuture<Void> enableReplicationPeer(String peerId);
682
683  /**
684   * Stop the replication stream to the specified peer
685   * @param peerId a short name that identifies the peer
686   */
687  CompletableFuture<Void> disableReplicationPeer(String peerId);
688
689  /**
690   * Returns the configured ReplicationPeerConfig for the specified peer
691   * @param peerId a short name that identifies the peer
692   * @return ReplicationPeerConfig for the peer wrapped by a {@link CompletableFuture}.
693   */
694  CompletableFuture<ReplicationPeerConfig> getReplicationPeerConfig(String peerId);
695
696  /**
697   * Update the peerConfig for the specified peer
698   * @param peerId a short name that identifies the peer
699   * @param peerConfig new config for the peer
700   */
701  CompletableFuture<Void> updateReplicationPeerConfig(String peerId,
702      ReplicationPeerConfig peerConfig);
703
704  /**
705   * Append the replicable table-cf config of the specified peer
706   * @param peerId a short that identifies the cluster
707   * @param tableCfs A map from tableName to column family names
708   */
709  CompletableFuture<Void> appendReplicationPeerTableCFs(String peerId,
710      Map<TableName, List<String>> tableCfs);
711
712  /**
713   * Remove some table-cfs from config of the specified peer
714   * @param peerId a short name that identifies the cluster
715   * @param tableCfs A map from tableName to column family names
716   */
717  CompletableFuture<Void> removeReplicationPeerTableCFs(String peerId,
718      Map<TableName, List<String>> tableCfs);
719
720  /**
721   * Return a list of replication peers.
722   * @return a list of replication peers description. The return value will be wrapped by a
723   *         {@link CompletableFuture}.
724   */
725  CompletableFuture<List<ReplicationPeerDescription>> listReplicationPeers();
726
727  /**
728   * Return a list of replication peers.
729   * @param pattern The compiled regular expression to match peer id
730   * @return a list of replication peers description. The return value will be wrapped by a
731   *         {@link CompletableFuture}.
732   */
733  CompletableFuture<List<ReplicationPeerDescription>> listReplicationPeers(Pattern pattern);
734
735  /**
736   * Find all table and column families that are replicated from this cluster
737   * @return the replicated table-cfs list of this cluster. The return value will be wrapped by a
738   *         {@link CompletableFuture}.
739   */
740  CompletableFuture<List<TableCFs>> listReplicatedTableCFs();
741
742  /**
743   * Enable a table's replication switch.
744   * @param tableName name of the table
745   */
746  CompletableFuture<Void> enableTableReplication(TableName tableName);
747
748  /**
749   * Disable a table's replication switch.
750   * @param tableName name of the table
751   */
752  CompletableFuture<Void> disableTableReplication(TableName tableName);
753
754  /**
755   * Take a snapshot for the given table. If the table is enabled, a FLUSH-type snapshot will be
756   * taken. If the table is disabled, an offline snapshot is taken. Snapshots are considered unique
757   * based on <b>the name of the snapshot</b>. Attempts to take a snapshot with the same name (even
758   * a different type or with different parameters) will fail with a
759   * {@link org.apache.hadoop.hbase.snapshot.SnapshotCreationException} indicating the duplicate
760   * naming. Snapshot names follow the same naming constraints as tables in HBase. See
761   * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
762   * @param snapshotName name of the snapshot to be created
763   * @param tableName name of the table for which snapshot is created
764   */
765  default CompletableFuture<Void> snapshot(String snapshotName, TableName tableName) {
766    return snapshot(snapshotName, tableName, SnapshotType.FLUSH);
767  }
768
769  /**
770   * Create typed snapshot of the table. Snapshots are considered unique based on <b>the name of the
771   * snapshot</b>. Attempts to take a snapshot with the same name (even a different type or with
772   * different parameters) will fail with a
773   * {@link org.apache.hadoop.hbase.snapshot.SnapshotCreationException} indicating the duplicate
774   * naming. Snapshot names follow the same naming constraints as tables in HBase. See
775   * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
776   * @param snapshotName name to give the snapshot on the filesystem. Must be unique from all other
777   *          snapshots stored on the cluster
778   * @param tableName name of the table to snapshot
779   * @param type type of snapshot to take
780   */
781  default CompletableFuture<Void> snapshot(String snapshotName, TableName tableName,
782      SnapshotType type) {
783    return snapshot(new SnapshotDescription(snapshotName, tableName, type));
784  }
785
786  /**
787   * Take a snapshot and wait for the server to complete that snapshot asynchronously. Only a single
788   * snapshot should be taken at a time for an instance of HBase, or results may be undefined (you
789   * can tell multiple HBase clusters to snapshot at the same time, but only one at a time for a
790   * single cluster). Snapshots are considered unique based on <b>the name of the snapshot</b>.
791   * Attempts to take a snapshot with the same name (even a different type or with different
792   * parameters) will fail with a {@link org.apache.hadoop.hbase.snapshot.SnapshotCreationException}
793   * indicating the duplicate naming. Snapshot names follow the same naming constraints as tables in
794   * HBase. See {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
795   * You should probably use {@link #snapshot(String, org.apache.hadoop.hbase.TableName)} unless you
796   * are sure about the type of snapshot that you want to take.
797   * @param snapshot snapshot to take
798   */
799  CompletableFuture<Void> snapshot(SnapshotDescription snapshot);
800
801  /**
802   * Check the current state of the passed snapshot. There are three possible states:
803   * <ol>
804   * <li>running - returns <tt>false</tt></li>
805   * <li>finished - returns <tt>true</tt></li>
806   * <li>finished with error - throws the exception that caused the snapshot to fail</li>
807   * </ol>
808   * The cluster only knows about the most recent snapshot. Therefore, if another snapshot has been
809   * run/started since the snapshot you are checking, you will receive an
810   * {@link org.apache.hadoop.hbase.snapshot.UnknownSnapshotException}.
811   * @param snapshot description of the snapshot to check
812   * @return <tt>true</tt> if the snapshot is completed, <tt>false</tt> if the snapshot is still
813   *         running
814   */
815  CompletableFuture<Boolean> isSnapshotFinished(SnapshotDescription snapshot);
816
817  /**
818   * Restore the specified snapshot on the original table. (The table must be disabled) If the
819   * "hbase.snapshot.restore.take.failsafe.snapshot" configuration property is set to true, a
820   * snapshot of the current table is taken before executing the restore operation. In case of
821   * restore failure, the failsafe snapshot will be restored. If the restore completes without
822   * problem the failsafe snapshot is deleted.
823   * @param snapshotName name of the snapshot to restore
824   */
825  CompletableFuture<Void> restoreSnapshot(String snapshotName);
826
827  /**
828   * Restore the specified snapshot on the original table. (The table must be disabled) If
829   * 'takeFailSafeSnapshot' is set to true, a snapshot of the current table is taken before
830   * executing the restore operation. In case of restore failure, the failsafe snapshot will be
831   * restored. If the restore completes without problem the failsafe snapshot is deleted. The
832   * failsafe snapshot name is configurable by using the property
833   * "hbase.snapshot.restore.failsafe.name".
834   * @param snapshotName name of the snapshot to restore
835   * @param takeFailSafeSnapshot true if the failsafe snapshot should be taken
836   */
837  default CompletableFuture<Void> restoreSnapshot(String snapshotName,
838      boolean takeFailSafeSnapshot) {
839    return restoreSnapshot(snapshotName, takeFailSafeSnapshot, false);
840  }
841
842  /**
843   * Restore the specified snapshot on the original table. (The table must be disabled) If
844   * 'takeFailSafeSnapshot' is set to true, a snapshot of the current table is taken before
845   * executing the restore operation. In case of restore failure, the failsafe snapshot will be
846   * restored. If the restore completes without problem the failsafe snapshot is deleted. The
847   * failsafe snapshot name is configurable by using the property
848   * "hbase.snapshot.restore.failsafe.name".
849   * @param snapshotName name of the snapshot to restore
850   * @param takeFailSafeSnapshot true if the failsafe snapshot should be taken
851   * @param restoreAcl <code>true</code> to restore acl of snapshot
852   */
853  CompletableFuture<Void> restoreSnapshot(String snapshotName, boolean takeFailSafeSnapshot,
854      boolean restoreAcl);
855
856  /**
857   * Create a new table by cloning the snapshot content.
858   * @param snapshotName name of the snapshot to be cloned
859   * @param tableName name of the table where the snapshot will be restored
860   */
861  default CompletableFuture<Void> cloneSnapshot(String snapshotName, TableName tableName) {
862    return cloneSnapshot(snapshotName, tableName, false);
863  }
864
865  /**
866   * Create a new table by cloning the snapshot content.
867   * @param snapshotName name of the snapshot to be cloned
868   * @param tableName name of the table where the snapshot will be restored
869   * @param restoreAcl <code>true</code> to restore acl of snapshot
870   */
871  CompletableFuture<Void> cloneSnapshot(String snapshotName, TableName tableName,
872      boolean restoreAcl);
873
874  /**
875   * List completed snapshots.
876   * @return a list of snapshot descriptors for completed snapshots wrapped by a
877   *         {@link CompletableFuture}
878   */
879  CompletableFuture<List<SnapshotDescription>> listSnapshots();
880
881  /**
882   * List all the completed snapshots matching the given pattern.
883   * @param pattern The compiled regular expression to match against
884   * @return - returns a List of SnapshotDescription wrapped by a {@link CompletableFuture}
885   */
886  CompletableFuture<List<SnapshotDescription>> listSnapshots(Pattern pattern);
887
888  /**
889   * List all the completed snapshots matching the given table name pattern.
890   * @param tableNamePattern The compiled table name regular expression to match against
891   * @return - returns a List of completed SnapshotDescription wrapped by a
892   *         {@link CompletableFuture}
893   */
894  CompletableFuture<List<SnapshotDescription>> listTableSnapshots(Pattern tableNamePattern);
895
896  /**
897   * List all the completed snapshots matching the given table name regular expression and snapshot
898   * name regular expression.
899   * @param tableNamePattern The compiled table name regular expression to match against
900   * @param snapshotNamePattern The compiled snapshot name regular expression to match against
901   * @return - returns a List of completed SnapshotDescription wrapped by a
902   *         {@link CompletableFuture}
903   */
904  CompletableFuture<List<SnapshotDescription>> listTableSnapshots(Pattern tableNamePattern,
905      Pattern snapshotNamePattern);
906
907  /**
908   * Delete an existing snapshot.
909   * @param snapshotName name of the snapshot
910   */
911  CompletableFuture<Void> deleteSnapshot(String snapshotName);
912
913  /**
914   * Delete all existing snapshots.
915   */
916  CompletableFuture<Void> deleteSnapshots();
917
918  /**
919   * Delete existing snapshots whose names match the pattern passed.
920   * @param pattern pattern for names of the snapshot to match
921   */
922  CompletableFuture<Void> deleteSnapshots(Pattern pattern);
923
924  /**
925   * Delete all existing snapshots matching the given table name pattern.
926   * @param tableNamePattern The compiled table name regular expression to match against
927   */
928  CompletableFuture<Void> deleteTableSnapshots(Pattern tableNamePattern);
929
930  /**
931   * Delete all existing snapshots matching the given table name regular expression and snapshot
932   * name regular expression.
933   * @param tableNamePattern The compiled table name regular expression to match against
934   * @param snapshotNamePattern The compiled snapshot name regular expression to match against
935   */
936  CompletableFuture<Void> deleteTableSnapshots(Pattern tableNamePattern,
937      Pattern snapshotNamePattern);
938
939  /**
940   * Execute a distributed procedure on a cluster.
941   * @param signature A distributed procedure is uniquely identified by its signature (default the
942   *          root ZK node name of the procedure).
943   * @param instance The instance name of the procedure. For some procedures, this parameter is
944   *          optional.
945   * @param props Property/Value pairs of properties passing to the procedure
946   */
947  CompletableFuture<Void> execProcedure(String signature, String instance,
948      Map<String, String> props);
949
950  /**
951   * Execute a distributed procedure on a cluster.
952   * @param signature A distributed procedure is uniquely identified by its signature (default the
953   *          root ZK node name of the procedure).
954   * @param instance The instance name of the procedure. For some procedures, this parameter is
955   *          optional.
956   * @param props Property/Value pairs of properties passing to the procedure
957   * @return data returned after procedure execution. null if no return data.
958   */
959  CompletableFuture<byte[]> execProcedureWithReturn(String signature, String instance,
960      Map<String, String> props);
961
962  /**
963   * Check the current state of the specified procedure. There are three possible states:
964   * <ol>
965   * <li>running - returns <tt>false</tt></li>
966   * <li>finished - returns <tt>true</tt></li>
967   * <li>finished with error - throws the exception that caused the procedure to fail</li>
968   * </ol>
969   * @param signature The signature that uniquely identifies a procedure
970   * @param instance The instance name of the procedure
971   * @param props Property/Value pairs of properties passing to the procedure
972   * @return true if the specified procedure is finished successfully, false if it is still running.
973   *         The value is wrapped by {@link CompletableFuture}
974   */
975  CompletableFuture<Boolean> isProcedureFinished(String signature, String instance,
976      Map<String, String> props);
977
978  /**
979   * Abort a procedure
980   * Do not use. Usually it is ignored but if not, it can do more damage than good. See hbck2.
981   * @param procId ID of the procedure to abort
982   * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
983   * @return true if aborted, false if procedure already completed or does not exist. the value is
984   *         wrapped by {@link CompletableFuture}
985   * @deprecated since 2.1.1 and will be removed in 4.0.0.
986   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
987   */
988  @Deprecated
989  CompletableFuture<Boolean> abortProcedure(long procId, boolean mayInterruptIfRunning);
990
991  /**
992   * List procedures
993   * @return procedure list JSON wrapped by {@link CompletableFuture}
994   */
995  CompletableFuture<String> getProcedures();
996
997  /**
998   * List locks.
999   * @return lock list JSON wrapped by {@link CompletableFuture}
1000   */
1001  CompletableFuture<String> getLocks();
1002
1003  /**
1004   * Mark region server(s) as decommissioned to prevent additional regions from getting
1005   * assigned to them. Optionally unload the regions on the servers. If there are multiple servers
1006   * to be decommissioned, decommissioning them at the same time can prevent wasteful region
1007   * movements. Region unloading is asynchronous.
1008   * @param servers The list of servers to decommission.
1009   * @param offload True to offload the regions from the decommissioned servers
1010   */
1011  CompletableFuture<Void> decommissionRegionServers(List<ServerName> servers, boolean offload);
1012
1013  /**
1014   * List region servers marked as decommissioned, which can not be assigned regions.
1015   * @return List of decommissioned region servers wrapped by {@link CompletableFuture}
1016   */
1017  CompletableFuture<List<ServerName>> listDecommissionedRegionServers();
1018
1019  /**
1020   * Remove decommission marker from a region server to allow regions assignments. Load regions onto
1021   * the server if a list of regions is given. Region loading is asynchronous.
1022   * @param server The server to recommission.
1023   * @param encodedRegionNames Regions to load onto the server.
1024   */
1025  CompletableFuture<Void> recommissionRegionServer(ServerName server,
1026      List<byte[]> encodedRegionNames);
1027
1028  /**
1029   * @return cluster status wrapped by {@link CompletableFuture}
1030   */
1031  CompletableFuture<ClusterMetrics> getClusterMetrics();
1032
1033  /**
1034   * @return cluster status wrapped by {@link CompletableFuture}
1035   */
1036  CompletableFuture<ClusterMetrics> getClusterMetrics(EnumSet<Option> options);
1037
1038  /**
1039   * @return current master server name wrapped by {@link CompletableFuture}
1040   */
1041  default CompletableFuture<ServerName> getMaster() {
1042    return getClusterMetrics(EnumSet.of(Option.MASTER)).thenApply(ClusterMetrics::getMasterName);
1043  }
1044
1045  /**
1046   * @return current backup master list wrapped by {@link CompletableFuture}
1047   */
1048  default CompletableFuture<Collection<ServerName>> getBackupMasters() {
1049    return getClusterMetrics(EnumSet.of(Option.BACKUP_MASTERS))
1050      .thenApply(ClusterMetrics::getBackupMasterNames);
1051  }
1052
1053  /**
1054   * @return current live region servers list wrapped by {@link CompletableFuture}
1055   */
1056  default CompletableFuture<Collection<ServerName>> getRegionServers() {
1057    return getClusterMetrics(EnumSet.of(Option.SERVERS_NAME))
1058        .thenApply(ClusterMetrics::getServersName);
1059  }
1060
1061  /**
1062   * @return a list of master coprocessors wrapped by {@link CompletableFuture}
1063   */
1064  default CompletableFuture<List<String>> getMasterCoprocessorNames() {
1065    return getClusterMetrics(EnumSet.of(Option.MASTER_COPROCESSORS))
1066        .thenApply(ClusterMetrics::getMasterCoprocessorNames);
1067  }
1068
1069  /**
1070   * Get the info port of the current master if one is available.
1071   * @return master info port
1072   */
1073  default CompletableFuture<Integer> getMasterInfoPort() {
1074    return getClusterMetrics(EnumSet.of(Option.MASTER_INFO_PORT)).thenApply(
1075      ClusterMetrics::getMasterInfoPort);
1076  }
1077
1078  /**
1079   * Shuts down the HBase cluster.
1080   */
1081  CompletableFuture<Void> shutdown();
1082
1083  /**
1084   * Shuts down the current HBase master only.
1085   */
1086  CompletableFuture<Void> stopMaster();
1087
1088  /**
1089   * Stop the designated regionserver.
1090   * @param serverName
1091   */
1092  CompletableFuture<Void> stopRegionServer(ServerName serverName);
1093
1094  /**
1095   * Update the configuration and trigger an online config change on the regionserver.
1096   * @param serverName : The server whose config needs to be updated.
1097   */
1098  CompletableFuture<Void> updateConfiguration(ServerName serverName);
1099
1100  /**
1101   * Update the configuration and trigger an online config change on all the masters and
1102   * regionservers.
1103   */
1104  CompletableFuture<Void> updateConfiguration();
1105
1106  /**
1107   * Roll the log writer. I.e. for filesystem based write ahead logs, start writing to a new file.
1108   * <p>
1109   * When the returned CompletableFuture is done, it only means the rollWALWriter request was sent
1110   * to the region server and may need some time to finish the rollWALWriter operation. As a side
1111   * effect of this call, the named region server may schedule store flushes at the request of the
1112   * wal.
1113   * @param serverName The servername of the region server.
1114   */
1115  CompletableFuture<Void> rollWALWriter(ServerName serverName);
1116
1117  /**
1118   * Clear compacting queues on a region server.
1119   * @param serverName
1120   * @param queues the set of queue name
1121   */
1122  CompletableFuture<Void> clearCompactionQueues(ServerName serverName, Set<String> queues);
1123
1124  /**
1125   * Get a list of {@link RegionMetrics} of all regions hosted on a region seerver.
1126   * @param serverName
1127   * @return a list of {@link RegionMetrics} wrapped by {@link CompletableFuture}
1128   */
1129  CompletableFuture<List<RegionMetrics>> getRegionMetrics(ServerName serverName);
1130
1131  /**
1132   * Get a list of {@link RegionMetrics} of all regions hosted on a region seerver for a table.
1133   * @param serverName
1134   * @param tableName
1135   * @return a list of {@link RegionMetrics} wrapped by {@link CompletableFuture}
1136   */
1137  CompletableFuture<List<RegionMetrics>> getRegionMetrics(ServerName serverName,
1138    TableName tableName);
1139
1140  /**
1141   * Check whether master is in maintenance mode
1142   * @return true if master is in maintenance mode, false otherwise. The return value will be
1143   *         wrapped by a {@link CompletableFuture}
1144   */
1145  CompletableFuture<Boolean> isMasterInMaintenanceMode();
1146
1147  /**
1148   * Get the current compaction state of a table. It could be in a major compaction, a minor
1149   * compaction, both, or none.
1150   * @param tableName table to examine
1151   * @return the current compaction state wrapped by a {@link CompletableFuture}
1152   */
1153  default CompletableFuture<CompactionState> getCompactionState(TableName tableName) {
1154    return getCompactionState(tableName, CompactType.NORMAL);
1155  }
1156
1157  /**
1158   * Get the current compaction state of a table. It could be in a major compaction, a minor
1159   * compaction, both, or none.
1160   * @param tableName table to examine
1161   * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
1162   * @return the current compaction state wrapped by a {@link CompletableFuture}
1163   */
1164  CompletableFuture<CompactionState> getCompactionState(TableName tableName,
1165      CompactType compactType);
1166
1167  /**
1168   * Get the current compaction state of region. It could be in a major compaction, a minor
1169   * compaction, both, or none.
1170   * @param regionName region to examine
1171   * @return the current compaction state wrapped by a {@link CompletableFuture}
1172   */
1173  CompletableFuture<CompactionState> getCompactionStateForRegion(byte[] regionName);
1174
1175  /**
1176   * Get the timestamp of the last major compaction for the passed table.
1177   * <p>
1178   * The timestamp of the oldest HFile resulting from a major compaction of that table, or not
1179   * present if no such HFile could be found.
1180   * @param tableName table to examine
1181   * @return the last major compaction timestamp wrapped by a {@link CompletableFuture}
1182   */
1183  CompletableFuture<Optional<Long>> getLastMajorCompactionTimestamp(TableName tableName);
1184
1185  /**
1186   * Get the timestamp of the last major compaction for the passed region.
1187   * <p>
1188   * The timestamp of the oldest HFile resulting from a major compaction of that region, or not
1189   * present if no such HFile could be found.
1190   * @param regionName region to examine
1191   * @return the last major compaction timestamp wrapped by a {@link CompletableFuture}
1192   */
1193  CompletableFuture<Optional<Long>> getLastMajorCompactionTimestampForRegion(byte[] regionName);
1194
1195  /**
1196   * @return the list of supported security capabilities. The return value will be wrapped by a
1197   *         {@link CompletableFuture}.
1198   */
1199  CompletableFuture<List<SecurityCapability>> getSecurityCapabilities();
1200
1201  /**
1202   * Turn the load balancer on or off.
1203   * @param on Set to <code>true</code> to enable, <code>false</code> to disable.
1204   * @return Previous balancer value wrapped by a {@link CompletableFuture}.
1205   */
1206  default CompletableFuture<Boolean> balancerSwitch(boolean on) {
1207    return balancerSwitch(on, false);
1208  }
1209
1210  /**
1211   * Turn the load balancer on or off.
1212   * <p/>
1213   * Notice that, the method itself is always non-blocking, which means it will always return
1214   * immediately. The {@code drainRITs} parameter only effects when will we complete the returned
1215   * {@link CompletableFuture}.
1216   * @param on Set to <code>true</code> to enable, <code>false</code> to disable.
1217   * @param drainRITs If <code>true</code>, it waits until current balance() call, if outstanding,
1218   *          to return.
1219   * @return Previous balancer value wrapped by a {@link CompletableFuture}.
1220   */
1221  CompletableFuture<Boolean> balancerSwitch(boolean on, boolean drainRITs);
1222
1223  /**
1224   * Invoke the balancer. Will run the balancer and if regions to move, it will go ahead and do the
1225   * reassignments. Can NOT run for various reasons. Check logs.
1226   * @return True if balancer ran, false otherwise. The return value will be wrapped by a
1227   *         {@link CompletableFuture}.
1228   */
1229  default CompletableFuture<Boolean> balance() {
1230    return balance(false);
1231  }
1232
1233  /**
1234   * Invoke the balancer. Will run the balancer and if regions to move, it will go ahead and do the
1235   * reassignments. If there is region in transition, force parameter of true would still run
1236   * balancer. Can *not* run for other reasons. Check logs.
1237   * @param forcible whether we should force balance even if there is region in transition.
1238   * @return True if balancer ran, false otherwise. The return value will be wrapped by a
1239   *         {@link CompletableFuture}.
1240   */
1241  CompletableFuture<Boolean> balance(boolean forcible);
1242
1243  /**
1244   * Query the current state of the balancer.
1245   * @return true if the balance switch is on, false otherwise. The return value will be wrapped by a
1246   *         {@link CompletableFuture}.
1247   */
1248  CompletableFuture<Boolean> isBalancerEnabled();
1249
1250  /**
1251   * Set region normalizer on/off.
1252   * @param on whether normalizer should be on or off
1253   * @return Previous normalizer value wrapped by a {@link CompletableFuture}
1254   */
1255  CompletableFuture<Boolean> normalizerSwitch(boolean on);
1256
1257  /**
1258   * Query the current state of the region normalizer
1259   * @return true if region normalizer is on, false otherwise. The return value will be wrapped by a
1260   *         {@link CompletableFuture}
1261   */
1262  CompletableFuture<Boolean> isNormalizerEnabled();
1263
1264  /**
1265   * Invoke region normalizer. Can NOT run for various reasons. Check logs.
1266   * @return true if region normalizer ran, false otherwise. The return value will be wrapped by a
1267   *         {@link CompletableFuture}
1268   */
1269  default CompletableFuture<Boolean> normalize() {
1270    return normalize(new NormalizeTableFilterParams.Builder().build());
1271  }
1272
1273  /**
1274   * Invoke region normalizer. Can NOT run for various reasons. Check logs.
1275   * @param ntfp limit to tables matching the specified filter.
1276   * @return true if region normalizer ran, false otherwise. The return value will be wrapped by a
1277   *         {@link CompletableFuture}
1278   */
1279  CompletableFuture<Boolean> normalize(NormalizeTableFilterParams ntfp);
1280
1281  /**
1282   * Turn the cleaner chore on/off.
1283   * @param on
1284   * @return Previous cleaner state wrapped by a {@link CompletableFuture}
1285   */
1286  CompletableFuture<Boolean> cleanerChoreSwitch(boolean on);
1287
1288  /**
1289   * Query the current state of the cleaner chore.
1290   * @return true if cleaner chore is on, false otherwise. The return value will be wrapped by
1291   *         a {@link CompletableFuture}
1292   */
1293  CompletableFuture<Boolean> isCleanerChoreEnabled();
1294
1295  /**
1296   * Ask for cleaner chore to run.
1297   * @return true if cleaner chore ran, false otherwise. The return value will be wrapped by a
1298   *         {@link CompletableFuture}
1299   */
1300  CompletableFuture<Boolean> runCleanerChore();
1301
1302  /**
1303   * Turn the catalog janitor on/off.
1304   * @param on
1305   * @return the previous state wrapped by a {@link CompletableFuture}
1306   */
1307  CompletableFuture<Boolean> catalogJanitorSwitch(boolean on);
1308
1309  /**
1310   * Query on the catalog janitor state.
1311   * @return true if the catalog janitor is on, false otherwise. The return value will be
1312   *         wrapped by a {@link CompletableFuture}
1313   */
1314  CompletableFuture<Boolean> isCatalogJanitorEnabled();
1315
1316  /**
1317   * Ask for a scan of the catalog table.
1318   * @return the number of entries cleaned. The return value will be wrapped by a
1319   *         {@link CompletableFuture}
1320   */
1321  CompletableFuture<Integer> runCatalogJanitor();
1322
1323  /**
1324   * Execute the given coprocessor call on the master.
1325   * <p>
1326   * The {@code stubMaker} is just a delegation to the {@code newStub} call. Usually it is only a
1327   * one line lambda expression, like:
1328   *
1329   * <pre>
1330   * <code>
1331   * channel -> xxxService.newStub(channel)
1332   * </code>
1333   * </pre>
1334   * @param stubMaker a delegation to the actual {@code newStub} call.
1335   * @param callable a delegation to the actual protobuf rpc call. See the comment of
1336   *          {@link ServiceCaller} for more details.
1337   * @param <S> the type of the asynchronous stub
1338   * @param <R> the type of the return value
1339   * @return the return value of the protobuf rpc call, wrapped by a {@link CompletableFuture}.
1340   * @see ServiceCaller
1341   */
1342  <S, R> CompletableFuture<R> coprocessorService(Function<RpcChannel, S> stubMaker,
1343      ServiceCaller<S, R> callable);
1344
1345  /**
1346   * Execute the given coprocessor call on the given region server.
1347   * <p>
1348   * The {@code stubMaker} is just a delegation to the {@code newStub} call. Usually it is only a
1349   * one line lambda expression, like:
1350   *
1351   * <pre>
1352   * <code>
1353   * channel -> xxxService.newStub(channel)
1354   * </code>
1355   * </pre>
1356   * @param stubMaker a delegation to the actual {@code newStub} call.
1357   * @param callable a delegation to the actual protobuf rpc call. See the comment of
1358   *          {@link ServiceCaller} for more details.
1359   * @param serverName the given region server
1360   * @param <S> the type of the asynchronous stub
1361   * @param <R> the type of the return value
1362   * @return the return value of the protobuf rpc call, wrapped by a {@link CompletableFuture}.
1363   * @see ServiceCaller
1364   */
1365  <S, R> CompletableFuture<R> coprocessorService(Function<RpcChannel, S> stubMaker,
1366    ServiceCaller<S, R> callable, ServerName serverName);
1367
1368  /**
1369   * List all the dead region servers.
1370   */
1371  default CompletableFuture<List<ServerName>> listDeadServers() {
1372    return this.getClusterMetrics(EnumSet.of(Option.DEAD_SERVERS))
1373        .thenApply(ClusterMetrics::getDeadServerNames);
1374  }
1375
1376  /**
1377   * Clear dead region servers from master.
1378   * @param servers list of dead region servers.
1379   * @return - returns a list of servers that not cleared wrapped by a {@link CompletableFuture}.
1380   */
1381  CompletableFuture<List<ServerName>> clearDeadServers(final List<ServerName> servers);
1382
1383  /**
1384   * Clear all the blocks corresponding to this table from BlockCache. For expert-admins. Calling
1385   * this API will drop all the cached blocks specific to a table from BlockCache. This can
1386   * significantly impact the query performance as the subsequent queries will have to retrieve the
1387   * blocks from underlying filesystem.
1388   * @param tableName table to clear block cache
1389   * @return CacheEvictionStats related to the eviction wrapped by a {@link CompletableFuture}.
1390   */
1391  CompletableFuture<CacheEvictionStats> clearBlockCache(final TableName tableName);
1392
1393  /**
1394   * Create a new table by cloning the existent table schema.
1395   *
1396   * @param tableName name of the table to be cloned
1397   * @param newTableName name of the new table where the table will be created
1398   * @param preserveSplits True if the splits should be preserved
1399   */
1400  CompletableFuture<Void>  cloneTableSchema(final TableName tableName,
1401      final TableName newTableName, final boolean preserveSplits);
1402
1403  /**
1404   * Turn the compaction on or off. Disabling compactions will also interrupt any currently ongoing
1405   * compactions. This state is ephemeral. The setting will be lost on restart. Compaction
1406   * can also be enabled/disabled by modifying configuration hbase.regionserver.compaction.enabled
1407   * in hbase-site.xml.
1408   *
1409   * @param switchState     Set to <code>true</code> to enable, <code>false</code> to disable.
1410   * @param serverNamesList list of region servers.
1411   * @return Previous compaction states for region servers
1412   */
1413  CompletableFuture<Map<ServerName, Boolean>> compactionSwitch(boolean switchState,
1414      List<String> serverNamesList);
1415
1416  /**
1417   * Switch the rpc throttle enabled state.
1418   * @param enable Set to <code>true</code> to enable, <code>false</code> to disable.
1419   * @return Previous rpc throttle enabled value
1420   */
1421  CompletableFuture<Boolean> switchRpcThrottle(boolean enable);
1422
1423  /**
1424   * Get if the rpc throttle is enabled.
1425   * @return True if rpc throttle is enabled
1426   */
1427  CompletableFuture<Boolean> isRpcThrottleEnabled();
1428
1429  /**
1430   * Switch the exceed throttle quota. If enabled, user/table/namespace throttle quota
1431   * can be exceeded if region server has availble quota.
1432   * @param enable Set to <code>true</code> to enable, <code>false</code> to disable.
1433   * @return Previous exceed throttle enabled value
1434   */
1435  CompletableFuture<Boolean> exceedThrottleQuotaSwitch(boolean enable);
1436
1437  /**
1438   * Fetches the table sizes on the filesystem as tracked by the HBase Master.
1439   */
1440  CompletableFuture<Map<TableName, Long>> getSpaceQuotaTableSizes();
1441
1442  /**
1443   * Fetches the observed {@link SpaceQuotaSnapshotView}s observed by a RegionServer.
1444   */
1445  CompletableFuture<? extends Map<TableName, ? extends SpaceQuotaSnapshotView>>
1446      getRegionServerSpaceQuotaSnapshots(ServerName serverName);
1447
1448  /**
1449   * Returns the Master's view of a quota on the given {@code namespace} or null if the Master has
1450   * no quota information on that namespace.
1451   */
1452  CompletableFuture<? extends SpaceQuotaSnapshotView>
1453      getCurrentSpaceQuotaSnapshot(String namespace);
1454
1455  /**
1456   * Returns the Master's view of a quota on the given {@code tableName} or null if the Master has
1457   * no quota information on that table.
1458   */
1459  CompletableFuture<? extends SpaceQuotaSnapshotView> getCurrentSpaceQuotaSnapshot(
1460      TableName tableName);
1461
1462  /**
1463   * Grants user specific permissions
1464   * @param userPermission user name and the specific permission
1465   * @param mergeExistingPermissions If set to false, later granted permissions will override
1466   *          previous granted permissions. otherwise, it'll merge with previous granted
1467   *          permissions.
1468   */
1469  CompletableFuture<Void> grant(UserPermission userPermission, boolean mergeExistingPermissions);
1470
1471  /**
1472   * Revokes user specific permissions
1473   * @param userPermission user name and the specific permission
1474   */
1475  CompletableFuture<Void> revoke(UserPermission userPermission);
1476
1477  /**
1478   * Get the global/namespace/table permissions for user
1479   * @param getUserPermissionsRequest A request contains which user, global, namespace or table
1480   *          permissions needed
1481   * @return The user and permission list
1482   */
1483  CompletableFuture<List<UserPermission>>
1484      getUserPermissions(GetUserPermissionsRequest getUserPermissionsRequest);
1485
1486  /**
1487   * Check if the user has specific permissions
1488   * @param userName the user name
1489   * @param permissions the specific permission list
1490   * @return True if user has the specific permissions
1491   */
1492  CompletableFuture<List<Boolean>> hasUserPermissions(String userName,
1493      List<Permission> permissions);
1494
1495  /**
1496   * Check if call user has specific permissions
1497   * @param permissions the specific permission list
1498   * @return True if user has the specific permissions
1499   */
1500  default CompletableFuture<List<Boolean>> hasUserPermissions(List<Permission> permissions) {
1501    return hasUserPermissions(null, permissions);
1502  }
1503
1504  /**
1505   * Turn on or off the auto snapshot cleanup based on TTL.
1506   * <p/>
1507   * Notice that, the method itself is always non-blocking, which means it will always return
1508   * immediately. The {@code sync} parameter only effects when will we complete the returned
1509   * {@link CompletableFuture}.
1510   *
1511   * @param on Set to <code>true</code> to enable, <code>false</code> to disable.
1512   * @param sync If <code>true</code>, it waits until current snapshot cleanup is completed,
1513   *   if outstanding.
1514   * @return Previous auto snapshot cleanup value wrapped by a {@link CompletableFuture}.
1515   */
1516  CompletableFuture<Boolean> snapshotCleanupSwitch(boolean on, boolean sync);
1517
1518  /**
1519   * Query the current state of the auto snapshot cleanup based on TTL.
1520   *
1521   * @return true if the auto snapshot cleanup is enabled, false otherwise.
1522   *   The return value will be wrapped by a {@link CompletableFuture}.
1523   */
1524  CompletableFuture<Boolean> isSnapshotCleanupEnabled();
1525
1526  /**
1527   * Retrieves online slow RPC logs from the provided list of
1528   * RegionServers
1529   *
1530   * @param serverNames Server names to get slowlog responses from
1531   * @param logQueryFilter filter to be used if provided
1532   * @return Online slowlog response list. The return value wrapped by a {@link CompletableFuture}
1533   * @deprecated since 2.4.0 and will be removed in 4.0.0.
1534   *   Use {@link #getLogEntries(Set, String, ServerType, int, Map)} instead.
1535   */
1536  @Deprecated
1537  default CompletableFuture<List<OnlineLogRecord>> getSlowLogResponses(
1538      final Set<ServerName> serverNames, final LogQueryFilter logQueryFilter) {
1539    String logType;
1540    if (LogQueryFilter.Type.LARGE_LOG.equals(logQueryFilter.getType())) {
1541      logType = "LARGE_LOG";
1542    } else {
1543      logType = "SLOW_LOG";
1544    }
1545    Map<String, Object> filterParams = new HashMap<>();
1546    filterParams.put("regionName", logQueryFilter.getRegionName());
1547    filterParams.put("clientAddress", logQueryFilter.getClientAddress());
1548    filterParams.put("tableName", logQueryFilter.getTableName());
1549    filterParams.put("userName", logQueryFilter.getUserName());
1550    filterParams.put("filterByOperator", logQueryFilter.getFilterByOperator().toString());
1551    CompletableFuture<List<LogEntry>> logEntries =
1552      getLogEntries(serverNames, logType, ServerType.REGION_SERVER, logQueryFilter.getLimit(),
1553        filterParams);
1554    return logEntries.thenApply(
1555      logEntryList -> logEntryList.stream().map(logEntry -> (OnlineLogRecord) logEntry)
1556        .collect(Collectors.toList()));
1557  }
1558
1559  /**
1560   * Clears online slow RPC logs from the provided list of
1561   * RegionServers
1562   *
1563   * @param serverNames Set of Server names to clean slowlog responses from
1564   * @return List of booleans representing if online slowlog response buffer is cleaned
1565   *   from each RegionServer. The return value wrapped by a {@link CompletableFuture}
1566   */
1567  CompletableFuture<List<Boolean>> clearSlowLogResponses(final Set<ServerName> serverNames);
1568
1569  /**
1570   * Retrieve recent online records from HMaster / RegionServers.
1571   * Examples include slow/large RPC logs, balancer decisions by master.
1572   *
1573   * @param serverNames servers to retrieve records from, useful in case of records maintained
1574   *   by RegionServer as we can select specific server. In case of servertype=MASTER, logs will
1575   *   only come from the currently active master.
1576   * @param logType string representing type of log records
1577   * @param serverType enum for server type: HMaster or RegionServer
1578   * @param limit put a limit to list of records that server should send in response
1579   * @param filterParams additional filter params
1580   * @return Log entries representing online records from servers
1581   */
1582  CompletableFuture<List<LogEntry>> getLogEntries(Set<ServerName> serverNames, String logType,
1583    ServerType serverType, int limit, Map<String, Object> filterParams);
1584}