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    * Stop the designated regionserver
963    *
964    * @param hostnamePort Hostname and port delimited by a <code>:</code> as in
965    * <code>example.org:1234</code>
966    * @throws IOException if a remote or network exception occurs
967    */
968   void stopRegionServer(final String hostnamePort) throws IOException;
969
970   /**
971    * @return cluster status
972    * @throws IOException if a remote or network exception occurs
973    */
974   ClusterStatus getClusterStatus() throws IOException;
975
976   /**
977    * @return Configuration used by the instance.
978    */
979   Configuration getConfiguration();
980
981   /**
982    * Create a new namespace. Blocks until namespace has been successfully created or an exception
983    * is thrown.
984    *
985    * @param descriptor descriptor which describes the new namespace
986    */
987   void createNamespace(final NamespaceDescriptor descriptor)
988   throws IOException;
989
990   /**
991    * Create a new namespace
992    *
993    * @param descriptor descriptor which describes the new namespace
994    * @return the result of the async create namespace operation. Use Future.get(long, TimeUnit) to
995    *  wait on the operation to complete.
996    */
997   Future<Void> createNamespaceAsync(final NamespaceDescriptor descriptor)
998   throws IOException;
999
1000   /**
1001    * Modify an existing namespace.  Blocks until namespace has been successfully modified or an
1002    * exception is thrown.
1003    *
1004    * @param descriptor descriptor which describes the new namespace
1005    */
1006   void modifyNamespace(final NamespaceDescriptor descriptor)
1007   throws IOException;
1008
1009   /**
1010    * Modify an existing namespace
1011    *
1012    * @param descriptor descriptor which describes the new namespace
1013    * @return the result of the async modify namespace operation. Use Future.get(long, TimeUnit) to
1014    *  wait on the operation to complete.
1015    */
1016   Future<Void> modifyNamespaceAsync(final NamespaceDescriptor descriptor)
1017   throws IOException;
1018
1019   /**
1020    * Delete an existing namespace. Only empty namespaces (no tables) can be removed.
1021    * Blocks until namespace has been successfully deleted or an
1022    * exception is thrown.
1023    *
1024    * @param name namespace name
1025    */
1026   void deleteNamespace(final String name) throws IOException;
1027
1028   /**
1029    * Delete an existing namespace. Only empty namespaces (no tables) can be removed.
1030    *
1031    * @param name namespace name
1032    * @return the result of the async delete namespace operation. Use Future.get(long, TimeUnit) to
1033    *  wait on the operation to complete.
1034    */
1035   Future<Void> deleteNamespaceAsync(final String name) throws IOException;
1036
1037   /**
1038    * Get a namespace descriptor by name
1039    *
1040    * @param name name of namespace descriptor
1041    * @return A descriptor
1042    */
1043   NamespaceDescriptor getNamespaceDescriptor(final String name)
1044   throws IOException;
1045
1046   /**
1047    * List available namespace descriptors
1048    *
1049    * @return List of descriptors
1050    */
1051   NamespaceDescriptor[] listNamespaceDescriptors()
1052   throws IOException;
1053
1054   /**
1055    * Get list of table descriptors by namespace
1056    *
1057    * @param name namespace name
1058    * @return A descriptor
1059    * @throws IOException
1060    */
1061   HTableDescriptor[] listTableDescriptorsByNamespace(final String name)
1062       throws IOException;
1063
1064   /**
1065    * Get list of table names by namespace
1066    *
1067    * @param name namespace name
1068    * @return The list of table names in the namespace
1069    * @throws IOException
1070    */
1071   TableName[] listTableNamesByNamespace(final String name)
1072       throws IOException;
1073
1074   /**
1075    * Get the regions of a given table.
1076    *
1077    * @param tableName the name of the table
1078    * @return List of {@link HRegionInfo}.
1079    * @throws IOException
1080    */
1081   List<HRegionInfo> getTableRegions(final TableName tableName)
1082     throws IOException;
1083
1084   @Override
1085   void close() throws IOException;
1086
1087   /**
1088    * Get tableDescriptors
1089    *
1090    * @param tableNames List of table names
1091    * @return HTD[] the tableDescriptor
1092    * @throws IOException if a remote or network exception occurs
1093    */
1094   HTableDescriptor[] getTableDescriptorsByTableName(List<TableName> tableNames)
1095     throws IOException;
1096
1097   /**
1098    * Get tableDescriptors
1099    *
1100    * @param names List of table names
1101    * @return HTD[] the tableDescriptor
1102    * @throws IOException if a remote or network exception occurs
1103    */
1104   HTableDescriptor[] getTableDescriptors(List<String> names)
1105     throws IOException;
1106
1107   /**
1108    * abort a procedure
1109    * @param procId ID of the procedure to abort
1110    * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
1111    * @return true if aborted, false if procedure already completed or does not exist
1112    * @throws IOException
1113    */
1114   boolean abortProcedure(
1115       final long procId,
1116       final boolean mayInterruptIfRunning) throws IOException;
1117
1118   /**
1119    * Abort a procedure but does not block and wait for it be completely removed.
1120    * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
1121    * It may throw ExecutionException if there was an error while executing the operation
1122    * or TimeoutException in case the wait timeout was not long enough to allow the
1123    * operation to complete.
1124    *
1125    * @param procId ID of the procedure to abort
1126    * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
1127    * @return true if aborted, false if procedure already completed or does not exist
1128    * @throws IOException
1129    */
1130   Future<Boolean> abortProcedureAsync(
1131     final long procId,
1132     final boolean mayInterruptIfRunning) throws IOException;
1133
1134   /**
1135    * List procedures
1136    * @return procedure list
1137    * @throws IOException
1138    */
1139   ProcedureInfo[] listProcedures()
1140       throws IOException;
1141
1142   /**
1143    * Roll the log writer. I.e. for filesystem based write ahead logs, start writing to a new file.
1144    *
1145    * Note that the actual rolling of the log writer is asynchronous and may not be complete when
1146    * this method returns. As a side effect of this call, the named region server may schedule
1147    * store flushes at the request of the wal.
1148    *
1149    * @param serverName The servername of the regionserver.
1150    * @throws IOException if a remote or network exception occurs
1151    * @throws org.apache.hadoop.hbase.regionserver.wal.FailedLogCloseException
1152    */
1153   void rollWALWriter(ServerName serverName) throws IOException, FailedLogCloseException;
1154
1155   /**
1156    * Helper delegage to getClusterStatus().getMasterCoprocessors().
1157    * @return an array of master coprocessors
1158    * @see org.apache.hadoop.hbase.ClusterStatus#getMasterCoprocessors()
1159    */
1160   String[] getMasterCoprocessors() throws IOException;
1161
1162   /**
1163    * Get the current compaction state of a table. It could be in a major compaction, a minor
1164    * compaction, both, or none.
1165    *
1166    * @param tableName table to examine
1167    * @return the current compaction state
1168    * @throws IOException if a remote or network exception occurs
1169    */
1170   CompactionState getCompactionState(final TableName tableName)
1171     throws IOException;
1172
1173   /**
1174    * Get the current compaction state of region. It could be in a major compaction, a minor
1175    * compaction, both, or none.
1176    *
1177    * @param regionName region to examine
1178    * @return the current compaction state
1179    * @throws IOException if a remote or network exception occurs
1180    */
1181   CompactionState getCompactionStateForRegion(
1182     final byte[] regionName) throws IOException;
1183
1184   /**
1185    * Get the timestamp of the last major compaction for the passed table
1186    *
1187    * The timestamp of the oldest HFile resulting from a major compaction of that table,
1188    * or 0 if no such HFile could be found.
1189    *
1190    * @param tableName table to examine
1191    * @return the last major compaction timestamp or 0
1192    * @throws IOException if a remote or network exception occurs
1193    */
1194   long getLastMajorCompactionTimestamp(final TableName tableName)
1195     throws IOException;
1196
1197   /**
1198    * Get the timestamp of the last major compaction for the passed region.
1199    *
1200    * The timestamp of the oldest HFile resulting from a major compaction of that region,
1201    * or 0 if no such HFile could be found.
1202    *
1203    * @param regionName region to examine
1204    * @return the last major compaction timestamp or 0
1205    * @throws IOException if a remote or network exception occurs
1206    */
1207   long getLastMajorCompactionTimestampForRegion(final byte[] regionName)
1208       throws IOException;
1209
1210   /**
1211    * Take a snapshot for the given table. If the table is enabled, a FLUSH-type snapshot will be
1212    * taken. If the table is disabled, an offline snapshot is taken. Snapshots are considered unique
1213    * based on <b>the name of the snapshot</b>. Attempts to take a snapshot with the same name (even
1214    * a different type or with different parameters) will fail with a {@link
1215    * org.apache.hadoop.hbase.snapshot.SnapshotCreationException} indicating the duplicate naming.
1216    * Snapshot names follow the same naming constraints as tables in HBase. See {@link
1217    * org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
1218    *
1219    * @param snapshotName name of the snapshot to be created
1220    * @param tableName name of the table for which snapshot is created
1221    * @throws IOException if a remote or network exception occurs
1222    * @throws org.apache.hadoop.hbase.snapshot.SnapshotCreationException if snapshot creation failed
1223    * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1224    */
1225   void snapshot(final String snapshotName, final TableName tableName)
1226       throws IOException, SnapshotCreationException, IllegalArgumentException;
1227
1228   /**
1229    * Create a timestamp consistent snapshot for the given table. Snapshots are considered unique
1230    * based on <b>the name of the snapshot</b>. Attempts to take a snapshot with the same name (even
1231    * different type or with different parameters) will fail with a {@link SnapshotCreationException}
1232    * indicating the duplicate naming. Snapshot names follow the same naming constraints as tables in
1233    * HBase.
1234    *
1235    * @param snapshotName name of the snapshot to be created
1236    * @param tableName name of the table for which snapshot is created
1237    * @throws IOException if a remote or network exception occurs
1238    * @throws SnapshotCreationException if snapshot creation failed
1239    * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1240    */
1241   void snapshot(final byte[] snapshotName, final TableName tableName)
1242       throws IOException, SnapshotCreationException, IllegalArgumentException;
1243
1244   /**
1245    * Create typed snapshot of the table. Snapshots are considered unique based on <b>the name of the
1246    * snapshot</b>. Attempts to take a snapshot with the same name (even a different type or with
1247    * different parameters) will fail with a {@link SnapshotCreationException} indicating the
1248    * duplicate naming. Snapshot names follow the same naming constraints as tables in HBase. See
1249    * {@link org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}.
1250    *
1251    * @param snapshotName name to give the snapshot on the filesystem. Must be unique from all other
1252    * snapshots stored on the cluster
1253    * @param tableName name of the table to snapshot
1254    * @param type type of snapshot to take
1255    * @throws IOException we fail to reach the master
1256    * @throws SnapshotCreationException if snapshot creation failed
1257    * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1258    */
1259   void snapshot(final String snapshotName,
1260       final TableName tableName,
1261       SnapshotType type) throws IOException, SnapshotCreationException,
1262       IllegalArgumentException;
1263
1264   /**
1265    * Take a snapshot and wait for the server to complete that snapshot (blocking). Only a single
1266    * snapshot should be taken at a time for an instance of HBase, or results may be undefined (you
1267    * can tell multiple HBase clusters to snapshot at the same time, but only one at a time for a
1268    * single cluster). Snapshots are considered unique based on <b>the name of the snapshot</b>.
1269    * Attempts to take a snapshot with the same name (even a different type or with different
1270    * parameters) will fail with a {@link SnapshotCreationException} indicating the duplicate naming.
1271    * Snapshot names follow the same naming constraints as tables in HBase. See {@link
1272    * org.apache.hadoop.hbase.TableName#isLegalFullyQualifiedTableName(byte[])}. You should probably
1273    * use {@link #snapshot(String, org.apache.hadoop.hbase.TableName)} or
1274    * {@link #snapshot(byte[], org.apache.hadoop.hbase.TableName)} unless you are sure about the type
1275    * of snapshot that you want to take.
1276    *
1277    * @param snapshot snapshot to take
1278    * @throws IOException or we lose contact with the master.
1279    * @throws SnapshotCreationException if snapshot failed to be taken
1280    * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1281    */
1282   void snapshot(SnapshotDescription snapshot)
1283       throws IOException, SnapshotCreationException, IllegalArgumentException;
1284
1285   /**
1286    * Take a snapshot without waiting for the server to complete that snapshot (asynchronous) Only a
1287    * single snapshot should be taken at a time, or results may be undefined.
1288    *
1289    * @param snapshot snapshot to take
1290    * @throws IOException if the snapshot did not succeed or we lose contact with the master.
1291    * @throws SnapshotCreationException if snapshot creation failed
1292    * @throws IllegalArgumentException if the snapshot request is formatted incorrectly
1293    */
1294   void takeSnapshotAsync(SnapshotDescription snapshot)
1295       throws IOException, SnapshotCreationException;
1296
1297   /**
1298    * Check the current state of the passed snapshot. There are three possible states: <ol>
1299    * <li>running - returns <tt>false</tt></li> <li>finished - returns <tt>true</tt></li>
1300    * <li>finished with error - throws the exception that caused the snapshot to fail</li> </ol> The
1301    * cluster only knows about the most recent snapshot. Therefore, if another snapshot has been
1302    * run/started since the snapshot your are checking, you will recieve an {@link
1303    * org.apache.hadoop.hbase.snapshot.UnknownSnapshotException}.
1304    *
1305    * @param snapshot description of the snapshot to check
1306    * @return <tt>true</tt> if the snapshot is completed, <tt>false</tt> if the snapshot is still
1307    * running
1308    * @throws IOException if we have a network issue
1309    * @throws org.apache.hadoop.hbase.snapshot.HBaseSnapshotException if the snapshot failed
1310    * @throws org.apache.hadoop.hbase.snapshot.UnknownSnapshotException if the requested snapshot is
1311    * unknown
1312    */
1313   boolean isSnapshotFinished(final SnapshotDescription snapshot)
1314       throws IOException, HBaseSnapshotException, UnknownSnapshotException;
1315
1316   /**
1317    * Restore the specified snapshot on the original table. (The table must be disabled) If the
1318    * "hbase.snapshot.restore.take.failsafe.snapshot" configuration property is set to true, a
1319    * snapshot of the current table is taken before executing the restore operation. In case of
1320    * restore failure, the failsafe snapshot will be restored. If the restore completes without
1321    * problem the failsafe snapshot is deleted.
1322    *
1323    * @param snapshotName name of the snapshot to restore
1324    * @throws IOException if a remote or network exception occurs
1325    * @throws org.apache.hadoop.hbase.snapshot.RestoreSnapshotException if snapshot failed to be
1326    * restored
1327    * @throws IllegalArgumentException if the restore request is formatted incorrectly
1328    */
1329   void restoreSnapshot(final byte[] snapshotName) throws IOException, RestoreSnapshotException;
1330
1331   /**
1332    * Restore the specified snapshot on the original table. (The table must be disabled) If the
1333    * "hbase.snapshot.restore.take.failsafe.snapshot" configuration property is set to true, a
1334    * snapshot of the current table is taken before executing the restore operation. In case of
1335    * restore failure, the failsafe snapshot will be restored. If the restore completes without
1336    * problem the failsafe snapshot is deleted.
1337    *
1338    * @param snapshotName name of the snapshot to restore
1339    * @throws IOException if a remote or network exception occurs
1340    * @throws RestoreSnapshotException if snapshot failed to be restored
1341    * @throws IllegalArgumentException if the restore request is formatted incorrectly
1342    */
1343   void restoreSnapshot(final String snapshotName) throws IOException, RestoreSnapshotException;
1344
1345   /**
1346    * Restore the specified snapshot on the original table. (The table must be disabled) If the
1347    * "hbase.snapshot.restore.take.failsafe.snapshot" configuration property is set to true, a
1348    * snapshot of the current table is taken before executing the restore operation. In case of
1349    * restore failure, the failsafe snapshot will be restored. If the restore completes without
1350    * problem the failsafe snapshot is deleted.
1351    *
1352    * @param snapshotName name of the snapshot to restore
1353    * @throws IOException if a remote or network exception occurs
1354    * @throws RestoreSnapshotException if snapshot failed to be restored
1355    * @return the result of the async restore snapshot. You can use Future.get(long, TimeUnit)
1356    *    to wait on the operation to complete.
1357    */
1358   Future<Void> restoreSnapshotAsync(final String snapshotName)
1359       throws IOException, RestoreSnapshotException;
1360
1361   /**
1362    * Restore the specified snapshot on the original table. (The table must be disabled) If
1363    * 'takeFailSafeSnapshot' is set to true, a snapshot of the current table is taken before
1364    * executing the restore operation. In case of restore failure, the failsafe snapshot will be
1365    * restored. If the restore completes without problem the failsafe snapshot is deleted. The
1366    * failsafe snapshot name is configurable by using the property
1367    * "hbase.snapshot.restore.failsafe.name".
1368    *
1369    * @param snapshotName name of the snapshot to restore
1370    * @param takeFailSafeSnapshot true if the failsafe snapshot should be taken
1371    * @throws IOException if a remote or network exception occurs
1372    * @throws RestoreSnapshotException if snapshot failed to be restored
1373    * @throws IllegalArgumentException if the restore request is formatted incorrectly
1374    */
1375   void restoreSnapshot(final byte[] snapshotName, final boolean takeFailSafeSnapshot)
1376       throws IOException, RestoreSnapshotException;
1377
1378   /**
1379    * Restore the specified snapshot on the original table. (The table must be disabled) If
1380    * 'takeFailSafeSnapshot' is set to true, a snapshot of the current table is taken before
1381    * executing the restore operation. In case of restore failure, the failsafe snapshot will be
1382    * restored. If the restore completes without problem the failsafe snapshot is deleted. The
1383    * failsafe snapshot name is configurable by using the property
1384    * "hbase.snapshot.restore.failsafe.name".
1385    *
1386    * @param snapshotName name of the snapshot to restore
1387    * @param takeFailSafeSnapshot true if the failsafe snapshot should be taken
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, final boolean takeFailSafeSnapshot)
1393       throws IOException, RestoreSnapshotException;
1394
1395   /**
1396    * Create a new table by cloning the snapshot content.
1397    *
1398    * @param snapshotName name of the snapshot to be cloned
1399    * @param tableName name of the table where the snapshot will be restored
1400    * @throws IOException if a remote or network exception occurs
1401    * @throws TableExistsException if table to be created already exists
1402    * @throws RestoreSnapshotException if snapshot failed to be cloned
1403    * @throws IllegalArgumentException if the specified table has not a valid name
1404    */
1405   void cloneSnapshot(final byte[] snapshotName, final TableName tableName)
1406       throws IOException, TableExistsException, RestoreSnapshotException;
1407
1408   /**
1409    * Create a new table by cloning the snapshot content.
1410    *
1411    * @param snapshotName name of the snapshot to be cloned
1412    * @param tableName name of the table where the snapshot will be restored
1413    * @throws IOException if a remote or network exception occurs
1414    * @throws TableExistsException if table to be created already exists
1415    * @throws RestoreSnapshotException if snapshot failed to be cloned
1416    * @throws IllegalArgumentException if the specified table has not a valid name
1417    */
1418   void cloneSnapshot(final String snapshotName, final TableName tableName)
1419       throws IOException, TableExistsException, RestoreSnapshotException;
1420
1421   /**
1422    * Create a new table by cloning the snapshot content, but does not block
1423    * and wait for it be completely cloned.
1424    * You can use Future.get(long, TimeUnit) to wait on the operation to complete.
1425    * It may throw ExecutionException if there was an error while executing the operation
1426    * or TimeoutException in case the wait timeout was not long enough to allow the
1427    * operation to complete.
1428    *
1429    * @param snapshotName name of the snapshot to be cloned
1430    * @param tableName name of the table where the snapshot will be restored
1431    * @throws IOException if a remote or network exception occurs
1432    * @throws TableExistsException if table to be cloned already exists
1433    * @return the result of the async clone snapshot. You can use Future.get(long, TimeUnit)
1434    *    to wait on the operation to complete.
1435    */
1436   Future<Void> cloneSnapshotAsync(final String snapshotName, final TableName tableName)
1437       throws IOException, TableExistsException;
1438
1439   /**
1440    * Execute a distributed procedure on a cluster.
1441    *
1442    * @param signature A distributed procedure is uniquely identified by its signature (default the
1443    * root ZK node name of the procedure).
1444    * @param instance The instance name of the procedure. For some procedures, this parameter is
1445    * optional.
1446    * @param props Property/Value pairs of properties passing to the procedure
1447    * @throws IOException
1448    */
1449   void execProcedure(String signature, String instance, Map<String, String> props)
1450       throws IOException;
1451
1452   /**
1453    * Execute a distributed procedure on a cluster.
1454    *
1455    * @param signature A distributed procedure is uniquely identified by its signature (default the
1456    * root ZK node name of the procedure).
1457    * @param instance The instance name of the procedure. For some procedures, this parameter is
1458    * optional.
1459    * @param props Property/Value pairs of properties passing to the procedure
1460    * @return data returned after procedure execution. null if no return data.
1461    * @throws IOException
1462    */
1463   byte[] execProcedureWithRet(String signature, String instance, Map<String, String> props)
1464       throws IOException;
1465
1466   /**
1467    * Check the current state of the specified procedure. There are three possible states: <ol>
1468    * <li>running - returns <tt>false</tt></li> <li>finished - returns <tt>true</tt></li>
1469    * <li>finished with error - throws the exception that caused the procedure to fail</li> </ol>
1470    *
1471    * @param signature The signature that uniquely identifies a procedure
1472    * @param instance The instance name of the procedure
1473    * @param props Property/Value pairs of properties passing to the procedure
1474    * @return true if the specified procedure is finished successfully, false if it is still running
1475    * @throws IOException if the specified procedure finished with error
1476    */
1477   boolean isProcedureFinished(String signature, String instance, Map<String, String> props)
1478       throws IOException;
1479
1480   /**
1481    * List completed snapshots.
1482    *
1483    * @return a list of snapshot descriptors for completed snapshots
1484    * @throws IOException if a network error occurs
1485    */
1486   List<SnapshotDescription> listSnapshots() throws IOException;
1487
1488   /**
1489    * List all the completed snapshots matching the given regular expression.
1490    *
1491    * @param regex The regular expression to match against
1492    * @return - returns a List of SnapshotDescription
1493    * @throws IOException if a remote or network exception occurs
1494    */
1495   List<SnapshotDescription> listSnapshots(String regex) throws IOException;
1496
1497   /**
1498    * List all the completed snapshots matching the given pattern.
1499    *
1500    * @param pattern The compiled regular expression to match against
1501    * @return - returns a List of SnapshotDescription
1502    * @throws IOException if a remote or network exception occurs
1503    */
1504   List<SnapshotDescription> listSnapshots(Pattern pattern) throws IOException;
1505
1506   /**
1507    * List all the completed snapshots matching the given table name regular expression and snapshot
1508    * name regular expression.
1509    * @param tableNameRegex The table name regular expression to match against
1510    * @param snapshotNameRegex The snapshot name regular expression to match against
1511    * @return - returns a List of completed SnapshotDescription
1512    * @throws IOException if a remote or network exception occurs
1513    */
1514   List<SnapshotDescription> listTableSnapshots(String tableNameRegex,
1515       String snapshotNameRegex) throws IOException;
1516
1517   /**
1518    * List all the completed snapshots matching the given table name regular expression and snapshot
1519    * name regular expression.
1520    * @param tableNamePattern The compiled table name regular expression to match against
1521    * @param snapshotNamePattern The compiled snapshot name regular expression to match against
1522    * @return - returns a List of completed SnapshotDescription
1523    * @throws IOException if a remote or network exception occurs
1524    */
1525   List<SnapshotDescription> listTableSnapshots(Pattern tableNamePattern,
1526       Pattern snapshotNamePattern) throws IOException;
1527
1528   /**
1529    * Delete an existing snapshot.
1530    *
1531    * @param snapshotName name of the snapshot
1532    * @throws IOException if a remote or network exception occurs
1533    */
1534   void deleteSnapshot(final byte[] snapshotName) throws IOException;
1535
1536   /**
1537    * Delete an existing snapshot.
1538    *
1539    * @param snapshotName name of the snapshot
1540    * @throws IOException if a remote or network exception occurs
1541    */
1542   void deleteSnapshot(final String snapshotName) throws IOException;
1543
1544   /**
1545    * Delete existing snapshots whose names match the pattern passed.
1546    *
1547    * @param regex The regular expression to match against
1548    * @throws IOException if a remote or network exception occurs
1549    */
1550   void deleteSnapshots(final String regex) throws IOException;
1551
1552   /**
1553    * Delete existing snapshots whose names match the pattern passed.
1554    *
1555    * @param pattern pattern for names of the snapshot to match
1556    * @throws IOException if a remote or network exception occurs
1557    */
1558   void deleteSnapshots(final Pattern pattern) throws IOException;
1559
1560   /**
1561    * Delete all existing snapshots matching the given table name regular expression and snapshot
1562    * name regular expression.
1563    * @param tableNameRegex The table name regular expression to match against
1564    * @param snapshotNameRegex The snapshot name regular expression to match against
1565    * @throws IOException if a remote or network exception occurs
1566    */
1567   void deleteTableSnapshots(String tableNameRegex, String snapshotNameRegex) throws IOException;
1568
1569   /**
1570    * Delete all existing snapshots matching the given table name regular expression and snapshot
1571    * name regular expression.
1572    * @param tableNamePattern The compiled table name regular expression to match against
1573    * @param snapshotNamePattern The compiled snapshot name regular expression to match against
1574    * @throws IOException if a remote or network exception occurs
1575    */
1576   void deleteTableSnapshots(Pattern tableNamePattern, Pattern snapshotNamePattern)
1577       throws IOException;
1578
1579   /**
1580    * Apply the new quota settings.
1581    *
1582    * @param quota the quota settings
1583    * @throws IOException if a remote or network exception occurs
1584    */
1585   void setQuota(final QuotaSettings quota) throws IOException;
1586
1587   /**
1588    * Return a QuotaRetriever to list the quotas based on the filter.
1589    *
1590    * @param filter the quota settings filter
1591    * @return the quota retriever
1592    * @throws IOException if a remote or network exception occurs
1593    */
1594   QuotaRetriever getQuotaRetriever(final QuotaFilter filter) throws IOException;
1595
1596   /**
1597    * Creates and returns a {@link com.google.protobuf.RpcChannel} instance connected to the active
1598    * master. <p> The obtained {@link com.google.protobuf.RpcChannel} instance can be used to access
1599    * a published coprocessor {@link com.google.protobuf.Service} using standard protobuf service
1600    * invocations: </p> <div style="background-color: #cccccc; padding: 2px">
1601    * <blockquote><pre>
1602    * CoprocessorRpcChannel channel = myAdmin.coprocessorService();
1603    * MyService.BlockingInterface service = MyService.newBlockingStub(channel);
1604    * MyCallRequest request = MyCallRequest.newBuilder()
1605    *     ...
1606    *     .build();
1607    * MyCallResponse response = service.myCall(null, request);
1608    * </pre></blockquote></div>
1609    *
1610    * @return A MasterCoprocessorRpcChannel instance
1611    */
1612   CoprocessorRpcChannel coprocessorService();
1613
1614
1615   /**
1616    * Creates and returns a {@link com.google.protobuf.RpcChannel} instance
1617    * connected to the passed region server.
1618    *
1619    * <p>
1620    * The obtained {@link com.google.protobuf.RpcChannel} instance can be used to access a published
1621    * coprocessor {@link com.google.protobuf.Service} using standard protobuf service invocations:
1622    * </p>
1623    *
1624    * <div style="background-color: #cccccc; padding: 2px">
1625    * <blockquote><pre>
1626    * CoprocessorRpcChannel channel = myAdmin.coprocessorService(serverName);
1627    * MyService.BlockingInterface service = MyService.newBlockingStub(channel);
1628    * MyCallRequest request = MyCallRequest.newBuilder()
1629    *     ...
1630    *     .build();
1631    * MyCallResponse response = service.myCall(null, request);
1632    * </pre></blockquote></div>
1633    *
1634    * @param sn the server name to which the endpoint call is made
1635    * @return A RegionServerCoprocessorRpcChannel instance
1636    */
1637   CoprocessorRpcChannel coprocessorService(ServerName sn);
1638
1639
1640   /**
1641    * Update the configuration and trigger an online config change
1642    * on the regionserver
1643    * @param server : The server whose config needs to be updated.
1644    * @throws IOException
1645    */
1646   void updateConfiguration(ServerName server) throws IOException;
1647
1648
1649   /**
1650    * Update the configuration and trigger an online config change
1651    * on all the regionservers
1652    * @throws IOException
1653    */
1654   void updateConfiguration() throws IOException;
1655
1656   /**
1657    * Get the info port of the current master if one is available.
1658    * @return master info port
1659    * @throws IOException
1660    */
1661   public int getMasterInfoPort() throws IOException;
1662
1663   /**
1664    * Compact a table. Asynchronous operation.
1665    *
1666    * @param tableName table to compact
1667    * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
1668    * @throws IOException
1669    * @throws InterruptedException
1670    */
1671   void compact(final TableName tableName, CompactType compactType)
1672     throws IOException, InterruptedException;
1673
1674   /**
1675    * Compact a column family within a table. Asynchronous operation.
1676    *
1677    * @param tableName table to compact
1678    * @param columnFamily column family within a table
1679    * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
1680    * @throws IOException if not a mob column family or if a remote or network exception occurs
1681    * @throws InterruptedException
1682    */
1683   void compact(final TableName tableName, final byte[] columnFamily, CompactType compactType)
1684     throws IOException, InterruptedException;
1685
1686   /**
1687    * Major compact a table. Asynchronous operation.
1688    *
1689    * @param tableName table to compact
1690    * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
1691    * @throws IOException
1692    * @throws InterruptedException
1693    */
1694   void majorCompact(final TableName tableName, CompactType compactType)
1695     throws IOException, InterruptedException;
1696
1697   /**
1698    * Major compact a column family within a table. Asynchronous operation.
1699    *
1700    * @param tableName table to compact
1701    * @param columnFamily column family within a table
1702    * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
1703    * @throws IOException if not a mob column family or if a remote or network exception occurs
1704    * @throws InterruptedException
1705    */
1706   void majorCompact(final TableName tableName, final byte[] columnFamily, CompactType compactType)
1707     throws IOException, InterruptedException;
1708
1709   /**
1710    * Get the current compaction state of a table. It could be in a compaction, or none.
1711    *
1712    * @param tableName table to examine
1713    * @param compactType {@link org.apache.hadoop.hbase.client.CompactType}
1714    * @return the current compaction state
1715    * @throws IOException if a remote or network exception occurs
1716    */
1717   CompactionState getCompactionState(final TableName tableName,
1718     CompactType compactType) throws IOException;
1719
1720   /**
1721    * Return the set of supported security capabilities.
1722    * @throws IOException
1723    * @throws UnsupportedOperationException
1724    */
1725   List<SecurityCapability> getSecurityCapabilities() throws IOException;
1726
1727   /**
1728    * Turn the Split or Merge switches on or off.
1729    *
1730    * @param enabled enabled or not
1731    * @param synchronous If true, it waits until current split() call, if outstanding, to return.
1732    * @param skipLock if false, we will do lock before change switch.
1733    *                 with the lock, other requests to change the switch will be rejected!
1734    *                 And when you set it to be false,
1735    *                 you should call {@link #releaseSplitOrMergeLockAndRollback()} by yourself
1736    * @param switchTypes switchType list {@link MasterSwitchType}
1737    * @return Previous switch value array
1738    */
1739   boolean[] setSplitOrMergeEnabled(final boolean enabled, final boolean synchronous,
1740                                    final boolean skipLock,
1741                                    final MasterSwitchType... switchTypes) throws IOException;
1742
1743   /**
1744    * Query the current state of the switch
1745    *
1746    * @return true if the switch is enabled, false otherwise.
1747    */
1748   boolean isSplitOrMergeEnabled(final MasterSwitchType switchType) throws IOException;
1749
1750   /**
1751    *  You should call this method after you call
1752    *  {@link #setSplitOrMergeEnabled(boolean, boolean, boolean, MasterSwitchType...)}
1753    *  with skipLock be false, this method will release the lock created by above method
1754    *  and rollback the switch state to be original state before you change switch
1755    * */
1756   void releaseSplitOrMergeLockAndRollback() throws IOException;
1757 }