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