001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.master;
019
020import java.io.IOException;
021import java.util.List;
022
023import org.apache.hadoop.hbase.NamespaceDescriptor;
024import org.apache.hadoop.hbase.ServiceNotRunningException;
025import org.apache.hadoop.hbase.master.procedure.ProcedurePrepareLatch;
026import org.apache.yetus.audience.InterfaceAudience;
027import org.apache.hadoop.hbase.util.NonceKey;
028
029/**
030 * View and edit the current cluster schema. Use this API making any modification to
031 * namespaces, tables, etc.
032 *
033 * <h2>Implementation Notes</h2>
034 * Nonces are for when operation is non-idempotent to ensure once-only semantic, even
035 * across process failures.
036 */
037// ClusterSchema is introduced to encapsulate schema modification. Currently the different aspects
038// are spread about the code base. This effort is about cleanup, shutting down access, and
039// coalescing common code. In particular, we'd contain filesystem modification. Other
040// benefits are to make all schema modification work the same way (one way to do an operation only
041// rather than the current approach where how an operation is done varies with context) and to make
042// it so clusterschema modification can stand apart from Master to faciliate standalone
043// testing. It is part of the filesystem refactor project that undoes the dependency on a
044// layout in HDFS that mimics our model of tables have regions have column families have files.
045// With this Interface in place, with all modifications going via this route where no filesystem
046// particulars are exposed, redoing our internals will take less effort.
047//
048// Currently ClusterSchema Interface will include namespace and table manipulation. Ideally a
049// form of this Interface will go all the ways down to the file manipulation level but currently
050// TBD.
051//
052// ClusterSchema is private to the Master; only the Master knows current cluster state and has
053// means of editing/altering it.
054//
055// TODO: Remove Server argument when MasterServices are passed.
056// TODO: We return Future<ProcedureInfo> in the below from most methods. It may change to return
057// a ProcedureFuture subsequently.
058@InterfaceAudience.Private
059public interface ClusterSchema {
060  /**
061   * Timeout for cluster operations in milliseconds.
062   */
063  public static final String HBASE_MASTER_CLUSTER_SCHEMA_OPERATION_TIMEOUT_KEY =
064      "hbase.master.cluster.schema.operation.timeout";
065  /**
066   * Default operation timeout in milliseconds.
067   */
068  public static final int DEFAULT_HBASE_MASTER_CLUSTER_SCHEMA_OPERATION_TIMEOUT =
069      5 * 60 * 1000;
070
071  /**
072   * For internals use only. Do not use! Provisionally part of this Interface.
073   * Prefer the high-level APIs available elsewhere in this API.
074   * @return Instance of {@link TableNamespaceManager}
075   */
076  // TODO: Remove from here. Keep internal. This Interface is too high-level to host this accessor.
077  TableNamespaceManager getTableNamespaceManager();
078
079  /**
080   * Create a new Namespace.
081   * @param namespaceDescriptor descriptor for new Namespace
082   * @param nonceKey A unique identifier for this operation from the client or process.
083   * @param latch A latch to block on for precondition validation
084   * @return procedure id
085   * @throws IOException if service is not running see {@link ServiceNotRunningException}
086   */
087  long createNamespace(NamespaceDescriptor namespaceDescriptor, NonceKey nonceKey, ProcedurePrepareLatch latch)
088  throws IOException;
089
090  /**
091   * Modify an existing Namespace.
092   * @param nonceKey A unique identifier for this operation from the client or process.
093   * @param latch A latch to block on for precondition validation
094   * @return procedure id
095   * @throws IOException if service is not running see {@link ServiceNotRunningException}
096   */
097  long modifyNamespace(NamespaceDescriptor descriptor, NonceKey nonceKey, ProcedurePrepareLatch latch)
098  throws IOException;
099
100  /**
101   * Delete an existing Namespace.
102   * Only empty Namespaces (no tables) can be removed.
103   * @param nonceKey A unique identifier for this operation from the client or process.
104   * @param latch A latch to block on for precondition validation
105   * @return procedure id
106   * @throws IOException if service is not running see {@link ServiceNotRunningException}
107   */
108  long deleteNamespace(String name, NonceKey nonceKey, ProcedurePrepareLatch latch)
109  throws IOException;
110
111  /**
112   * Get a Namespace
113   * @param name Name of the Namespace
114   * @return Namespace descriptor for <code>name</code>
115   * @throws IOException if namespace does not exist
116   */
117  // No Future here because presumption is that the request will go against cached metadata so
118  // return immediately -- no need of running a Procedure.
119  NamespaceDescriptor getNamespace(String name) throws IOException;
120
121  /**
122   * Get all Namespaces
123   * @return All Namespace descriptors
124   */
125  List<NamespaceDescriptor> getNamespaces() throws IOException;
126}