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.io.InterruptedIOException;
022import java.util.List;
023
024import org.apache.hadoop.hbase.NamespaceDescriptor;
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 Throws {@link ClusterSchemaException} and {@link InterruptedIOException}
086   *    as well as {@link IOException}
087   */
088  long createNamespace(NamespaceDescriptor namespaceDescriptor, NonceKey nonceKey, ProcedurePrepareLatch latch)
089  throws IOException;
090
091  /**
092   * Modify an existing Namespace.
093   * @param nonceKey A unique identifier for this operation from the client or process.
094   * @param latch A latch to block on for precondition validation
095   * @return procedure id
096   * @throws IOException Throws {@link ClusterSchemaException} and {@link InterruptedIOException}
097   *    as well as {@link IOException}
098   */
099  long modifyNamespace(NamespaceDescriptor descriptor, NonceKey nonceKey, ProcedurePrepareLatch latch)
100  throws IOException;
101
102  /**
103   * Delete an existing Namespace.
104   * Only empty Namespaces (no tables) can be removed.
105   * @param nonceKey A unique identifier for this operation from the client or process.
106   * @param latch A latch to block on for precondition validation
107   * @return procedure id
108   * @throws IOException Throws {@link ClusterSchemaException} and {@link InterruptedIOException}
109   *    as well as {@link IOException}
110   */
111  long deleteNamespace(String name, NonceKey nonceKey, ProcedurePrepareLatch latch)
112  throws IOException;
113
114  /**
115   * Get a Namespace
116   * @param name Name of the Namespace
117   * @return Namespace descriptor for <code>name</code>
118   * @throws IOException Throws {@link ClusterSchemaException} and {@link InterruptedIOException}
119   *    as well as {@link IOException}
120   */
121  // No Future here because presumption is that the request will go against cached metadata so
122  // return immediately -- no need of running a Procedure.
123  NamespaceDescriptor getNamespace(String name) throws IOException;
124
125  /**
126   * Get all Namespaces
127   * @return All Namespace descriptors
128   */
129  List<NamespaceDescriptor> getNamespaces() throws IOException;
130}