View Javadoc

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