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