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.testing;
019
020import java.util.List;
021import java.util.Optional;
022import java.util.concurrent.CompletableFuture;
023import org.apache.hadoop.conf.Configuration;
024import org.apache.hadoop.hbase.HBaseInterfaceAudience;
025import org.apache.hadoop.hbase.ServerName;
026import org.apache.hadoop.hbase.client.RegionInfo;
027import org.apache.hadoop.hbase.regionserver.OnlineRegions;
028import org.apache.hadoop.hbase.regionserver.Region;
029import org.apache.yetus.audience.InterfaceAudience;
030
031/**
032 * A mini hbase cluster used for testing.
033 * <p/>
034 * It will also start the necessary zookeeper cluster and dfs cluster. But we will not provide
035 * methods for controlling the zookeeper cluster and dfs cluster, as end users do not need to test
036 * the HBase behavior when these systems are broken.
037 * <p/>
038 * The implementation is not required to be thread safe, so do not call different methods
039 * concurrently.
040 */
041@InterfaceAudience.Public
042public interface TestingHBaseCluster {
043
044  /**
045   * Get configuration of this cluster.
046   * <p/>
047   * You could use the returned {@link Configuration} to create
048   * {@link org.apache.hadoop.hbase.client.Connection} for accessing the testing cluster.
049   */
050  Configuration getConf();
051
052  /**
053   * Start a new master with localhost and random port.
054   */
055  void startMaster() throws Exception;
056
057  /**
058   * Start a new master bind on the given host and port.
059   */
060  void startMaster(String hostname, int port) throws Exception;
061
062  /**
063   * Stop the given master.
064   * <p/>
065   * Wait on the returned {@link CompletableFuture} to wait on the master quit. The differences
066   * comparing to {@link org.apache.hadoop.hbase.client.Admin#stopMaster()} is that first, we could
067   * also stop backup masters here, second, this method does not always fail since we do not use rpc
068   * to stop the master.
069   */
070  CompletableFuture<Void> stopMaster(ServerName serverName) throws Exception;
071
072  /**
073   * Start a new region server with localhost and random port.
074   */
075  void startRegionServer() throws Exception;
076
077  /**
078   * Start a new region server bind on the given host and port.
079   */
080  void startRegionServer(String hostname, int port) throws Exception;
081
082  /**
083   * Stop the given region server.
084   * <p/>
085   * Wait on the returned {@link CompletableFuture} to wait on the master quit. The difference
086   * comparing to {@link org.apache.hadoop.hbase.client.Admin#stopMaster()} is that this method does
087   * not always fail since we do not use rpc to stop the region server.
088   */
089  CompletableFuture<Void> stopRegionServer(ServerName serverName) throws Exception;
090
091  /**
092   * Stop the hbase cluster.
093   * <p/>
094   * You need to call {@link #start()} first before calling this method, otherwise an
095   * {@link IllegalStateException} will be thrown. If the hbase is not running because you have
096   * already stopped the cluster, an {@link IllegalStateException} will be thrown too.
097   */
098  void stopHBaseCluster() throws Exception;
099
100  /**
101   * Start the hbase cluster.
102   * <p/>
103   * This is used to start the hbase cluster again after you call {@link #stopHBaseCluster()}. If
104   * the cluster is already running or you have not called {@link #start()} yet, an
105   * {@link IllegalStateException} will be thrown.
106   */
107  void startHBaseCluster() throws Exception;
108
109  /**
110   * Return whether the hbase cluster is running.
111   */
112  boolean isHBaseClusterRunning();
113
114  /**
115   * Start the whole mini cluster, including zookeeper cluster, dfs cluster and hbase cluster.
116   * <p/>
117   * You can only call this method once at the beginning, unless you have called {@link #stop()} to
118   * shutdown the cluster completely, and then you can call this method to start the whole cluster
119   * again. An {@link IllegalStateException} will be thrown if you call this method incorrectly.
120   */
121  void start() throws Exception;
122
123  /**
124   * Get the address of active master if there is one.
125   */
126  Optional<ServerName> getActiveMasterAddress();
127
128  /**
129   * Get all the backup master addresses.
130   */
131  List<ServerName> getBackupMasterAddresses();
132
133  /**
134   * Get all the region server addresses.
135   */
136  List<ServerName> getRegionServerAddresses();
137
138  /**
139   * Get the server side {@link Region} interface for the specific region.
140   * <p/>
141   * This is used for CPs to test something which can only be accessed at server side, such as tags.
142   */
143  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
144  Optional<Region> getRegion(RegionInfo regionInfo);
145
146  /**
147   * Get the server side {@link OnlineRegions} interface for the specific region server.
148   * <p/>
149   * You could list the addresses of all the region server through the
150   * {@link #getRegionServerAddresses()} method.
151   * <p/>
152   * This is used for CPs to test something which can only be accessed at server side, such as tags.
153   * And also you could use the returned interface to get all regions on this region server, etc.
154   */
155  @InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
156  Optional<OnlineRegions> getOnlineRegionsInterface(ServerName serverName);
157
158  /**
159   * Return whether the cluster is running.
160   * <p/>
161   * Notice that, this only means you have called {@link #start()} and have not called
162   * {@link #stop()} yet. If you want to make sure the hbase cluster is running, use
163   * {@link #isHBaseClusterRunning()}.
164   */
165  boolean isClusterRunning();
166
167  /**
168   * Stop the whole mini cluster, including zookeeper cluster, dfs cluster and hbase cluster.
169   * <p/>
170   * You can only call this method after calling {@link #start()}, otherwise an
171   * {@link IllegalStateException} will be thrown.
172   */
173  void stop() throws Exception;
174
175  /**
176   * Create a {@link TestingHBaseCluster}. You need to call {@link #start()} of the returned
177   * {@link TestingHBaseCluster} to actually start the mini testing cluster.
178   */
179  static TestingHBaseCluster create(TestingHBaseClusterOption option) {
180    return new TestingHBaseClusterImpl(option);
181  }
182}