*

* Licensed to the Apache Software Foundation (ASF) under one

* or more contributor license agreements.  See the NOTICE file

* distributed with this work for additional information

* regarding copyright ownership.  The ASF licenses this file

* to you under the Apache License, Version 2.0 (the

* "License"); you may not use this file except in compliance

* with the License.  You may obtain a copy of the License at

*

*     http://www.apache.org/licenses/LICENSE-2.0

*

* Unless required by applicable law or agreed to in writing, software

* distributed under the License is distributed on an "AS IS" BASIS,

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

* See the License for the specific language governing permissions and

* limitations under the License.

*/

* Provides an interface to manage HBase database table metadata + general

* administrative functions.  Use HBaseAdmin to create, drop, list, enable and

* disable tables. Use it also to add and drop table column families.

*

* <p>See {@link HTable} to add, update, and delete data from an individual table.

* <p>Currently HBaseAdmin instances are not expected to be long-lived.  For

* example, an HBaseAdmin instance will not ride over a Master restart.

*/

@InterfaceStability.Evolving

  private static final Log LOG = LogFactory.getLog(HBaseAdmin.class);

  // We use the implementation class rather then the interface because we

  //  need the package protected functions to get the connection to master

  private HConnection connection;

  private volatile Configuration conf;

  private final long pause;

  private final int numRetries;

  // Some operations can take a long time such as disable of big table.

  // numRetries is for 'normal' stuff... Multiply by this factor when

  // want to wait a long time.

  private final int retryLongerMultiplier;

  private boolean aborted;

  private boolean cleanupConnectionOnClose = false; // close the connection in close()

  private boolean closed = false;

  private RpcRetryingCallerFactory rpcCallerFactory;

  /**

   * Constructor.

   * See {@link #HBaseAdmin(HConnection connection)}

   *

   * @param c Configuration object. Copied internally.

   */

  public HBaseAdmin(Configuration c)

  throws MasterNotRunningException, ZooKeeperConnectionException, IOException {

    // Will not leak connections, as the new implementation of the constructor

    // does not throw exceptions anymore.

    this(HConnectionManager.getConnection(new Configuration(c)));

    this.cleanupConnectionOnClose = true;

  }

/**

  * Constructor for externally managed HConnections.

  * The connection to master will be created when required by admin functions.

  *

  * @param connection The HConnection instance to use

  * @throws MasterNotRunningException, ZooKeeperConnectionException are not

  *  thrown anymore but kept into the interface for backward api compatibility

  */

  public HBaseAdmin(HConnection connection)

      throws MasterNotRunningException, ZooKeeperConnectionException {

    this.conf = connection.getConfiguration();

    this.connection = connection;

    this.pause = this.conf.getLong(HConstants.HBASE_CLIENT_PAUSE,

        HConstants.DEFAULT_HBASE_CLIENT_PAUSE);

    this.numRetries = this.conf.getInt(HConstants.HBASE_CLIENT_RETRIES_NUMBER,

        HConstants.DEFAULT_HBASE_CLIENT_RETRIES_NUMBER);

    this.retryLongerMultiplier = this.conf.getInt(

        "hbase.client.retries.longer.multiplier", 10);

    this.rpcCallerFactory = RpcRetryingCallerFactory.instantiate(this.conf);

  }

  /**

   * @return A new CatalogTracker instance; call {@link #cleanupCatalogTracker(CatalogTracker)}

   * to cleanup the returned catalog tracker.

   * @throws org.apache.hadoop.hbase.ZooKeeperConnectionException

   * @throws IOException

   * @see #cleanupCatalogTracker(CatalogTracker)

   */

  private synchronized CatalogTracker getCatalogTracker()

  throws ZooKeeperConnectionException, IOException {

    CatalogTracker ct = null;

    try {

      ct = new CatalogTracker(this.conf);

      ct.start();

    } catch (InterruptedException e) {

      // Let it out as an IOE for now until we redo all so tolerate IEs

      throw (InterruptedIOException)new InterruptedIOException("Interrupted").initCause(e);

    }

    return ct;

  }

  private void cleanupCatalogTracker(final CatalogTracker ct) {

    ct.stop();

  }

  @Override

  public void abort(String why, Throwable e) {

    // Currently does nothing but throw the passed message and exception

    this.aborted = true;

    throw new RuntimeException(why, e);

  }

  @Override

  public boolean isAborted(){

    return this.aborted;

  }

  /** @return HConnection used by this object. */

  public HConnection getConnection() {

    return connection;

  }

  /** @return - true if the master server is running. Throws an exception

   *  otherwise.

   * @throws ZooKeeperConnectionException

   * @throws MasterNotRunningException

   */

  public boolean isMasterRunning()

  throws MasterNotRunningException, ZooKeeperConnectionException {

    return connection.isMasterRunning();

  }

  /**

   * @param tableName Table to check.

   * @return True if table exists already.

   * @throws IOException

   */

  public boolean tableExists(final TableName tableName)

  throws IOException {

    boolean b = false;

    CatalogTracker ct = getCatalogTracker();

    try {

      b = MetaReader.tableExists(ct, tableName);

    } finally {

      cleanupCatalogTracker(ct);

    }

    return b;

  }

  public boolean tableExists(final byte[] tableName)

  throws IOException {

    return tableExists(TableName.valueOf(tableName));

  }

  public boolean tableExists(final String tableName)

  throws IOException {

    return tableExists(TableName.valueOf(tableName));

  }

  /**

   * List all the userspace tables.  In other words, scan the hbase:meta table.

   *

   * If we wanted this to be really fast, we could implement a special

   * catalog table that just contains table names and their descriptors.

   * Right now, it only exists as part of the hbase:meta table's region info.

   *

   * @return - returns an array of HTableDescriptors

   * @throws IOException if a remote or network exception occurs

   */

  public HTableDescriptor[] listTables() throws IOException {

    return this.connection.listTables();

  }

  /**

   * List all the userspace tables matching the given pattern.

   *

   * @param pattern The compiled regular expression to match against

   * @return - returns an array of HTableDescriptors

   * @throws IOException if a remote or network exception occurs

   * @see #listTables()

   */

  public HTableDescriptor[] listTables(Pattern pattern) throws IOException {

    List<HTableDescriptor> matched = new LinkedList<HTableDescriptor>();

    HTableDescriptor[] tables = listTables();

    for (HTableDescriptor table : tables) {

      if (pattern.matcher(table.getTableName().getNameAsString()).matches()) {

        matched.add(table);

      }

    }

    return matched.toArray(new HTableDescriptor[matched.size()]);

  }

  /**

   * List all the userspace tables matching the given regular expression.

   *

   * @param regex The regular expression to match against

   * @return - returns an array of HTableDescriptors

   * @throws IOException if a remote or network exception occurs

   * @see #listTables(java.util.regex.Pattern)

   */

  public HTableDescriptor[] listTables(String regex) throws IOException {

    return listTables(Pattern.compile(regex));

  }

  /**

   * List all of the names of userspace tables.

   * @return String[] table names

   * @throws IOException if a remote or network exception occurs

   */

  @Deprecated

  public String[] getTableNames() throws IOException {

    return this.connection.getTableNames();

  }

  /**

   * List all of the names of userspace tables matching the given regular expression.

   * @param pattern The regular expression to match against

   * @return String[] table names

   * @throws IOException if a remote or network exception occurs

   */

  @Deprecated

  public String[] getTableNames(Pattern pattern) throws IOException {

    List<String> matched = new ArrayList<String>();

    for (String name: this.connection.getTableNames()) {

      if (pattern.matcher(name).matches()) {

        matched.add(name);

      }

    }

    return matched.toArray(new String[matched.size()]);

  }

  /**

   * List all of the names of userspace tables matching the given regular expression.

   * @param regex The regular expression to match against

   * @return String[] table names

   * @throws IOException if a remote or network exception occurs

   */

  @Deprecated

  public String[] getTableNames(String regex) throws IOException {

    return getTableNames(Pattern.compile(regex));

  }

  /**

   * List all of the names of userspace tables.

   * @return TableName[] table names

   * @throws IOException if a remote or network exception occurs

   */

  public TableName[] listTableNames() throws IOException {

    return this.connection.listTableNames();

  }

  /**

   * Method for getting the tableDescriptor

   * @param tableName as a byte []

   * @return the tableDescriptor

   * @throws TableNotFoundException

   * @throws IOException if a remote or network exception occurs

   */

  public HTableDescriptor getTableDescriptor(final TableName tableName)

  throws TableNotFoundException, IOException {

    return this.connection.getHTableDescriptor(tableName);

  }

  public HTableDescriptor getTableDescriptor(final byte[] tableName)

  throws TableNotFoundException, IOException {

    return getTableDescriptor(TableName.valueOf(tableName));

  }

  private long getPauseTime(int tries) {

    int triesCount = tries;

    if (triesCount >= HConstants.RETRY_BACKOFF.length) {

      triesCount = HConstants.RETRY_BACKOFF.length - 1;

    }

    return this.pause * HConstants.RETRY_BACKOFF[triesCount];

  }

  /**

   * Creates a new table.

   * Synchronous operation.

   *

   * @param desc table descriptor for table

   *

   * @throws IllegalArgumentException if the table name is reserved

   * @throws MasterNotRunningException if master is not running

   * @throws TableExistsException if table already exists (If concurrent

   * threads, the table may have been created between test-for-existence

   * and attempt-at-creation).

   * @throws IOException if a remote or network exception occurs

   */

  public void createTable(HTableDescriptor desc)

  throws IOException {

    createTable(desc, null);

  }

  /**

   * Creates a new table with the specified number of regions.  The start key

   * specified will become the end key of the first region of the table, and

   * the end key specified will become the start key of the last region of the

   * table (the first region has a null start key and the last region has a

   * null end key).

   *

   * BigInteger math will be used to divide the key range specified into

   * enough segments to make the required number of total regions.

   *

   * Synchronous operation.

   *

   * @param desc table descriptor for table

   * @param startKey beginning of key range

   * @param endKey end of key range

   * @param numRegions the total number of regions to create

   *

   * @throws IllegalArgumentException if the table name is reserved

   * @throws MasterNotRunningException if master is not running

   * @throws org.apache.hadoop.hbase.TableExistsException if table already exists (If concurrent

   * threads, the table may have been created between test-for-existence

   * and attempt-at-creation).

   * @throws IOException

   */

  public void createTable(HTableDescriptor desc, byte [] startKey,

      byte [] endKey, int numRegions)

  throws IOException {

    if(numRegions < 3) {

      throw new IllegalArgumentException("Must create at least three regions");

    } else if(Bytes.compareTo(startKey, endKey) >= 0) {

      throw new IllegalArgumentException("Start key must be smaller than end key");

    }

    if (numRegions == 3) {

      createTable(desc, new byte[][]{startKey, endKey});

      return;

    }

    byte [][] splitKeys = Bytes.split(startKey, endKey, numRegions - 3);

    if(splitKeys == null || splitKeys.length != numRegions - 1) {

      throw new IllegalArgumentException("Unable to split key range into enough regions");