View Javadoc

1   /**
2    * Copyright 2010 The Apache Software Foundation
3    *
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *     http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing, software
15   * distributed under the License is distributed on an "AS IS" BASIS,
16   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17   * See the License for the specific language governing permissions and
18   * limitations under the License.
19   */
20  package org.apache.hadoop.hbase.ipc;
21  
22  import java.io.IOException;
23  import java.util.List;
24  
25  import org.apache.hadoop.hbase.ClusterStatus;
26  import org.apache.hadoop.hbase.HColumnDescriptor;
27  import org.apache.hadoop.hbase.HTableDescriptor;
28  import org.apache.hadoop.hbase.UnknownRegionException;
29  import org.apache.hadoop.hbase.client.coprocessor.Exec;
30  import org.apache.hadoop.hbase.client.coprocessor.ExecResult;
31  import org.apache.hadoop.hbase.security.TokenInfo;
32  import org.apache.hadoop.hbase.security.KerberosInfo;
33  import org.apache.hadoop.hbase.snapshot.HSnapshotDescription;
34  import org.apache.hadoop.hbase.util.Pair;
35  
36  /**
37   * Clients interact with the HMasterInterface to gain access to meta-level
38   * HBase functionality, like finding an HRegionServer and creating/destroying
39   * tables.
40   *
41   * <p>NOTE: if you change the interface, you must change the RPC version
42   * number in HBaseRPCProtocolVersion
43   *
44   */
45  @KerberosInfo(
46      serverPrincipal = "hbase.master.kerberos.principal")
47  @TokenInfo("HBASE_AUTH_TOKEN")
48  public interface HMasterInterface extends VersionedProtocol {
49    /**
50     * This Interfaces' version. Version changes when the Interface changes.
51     */
52    // All HBase Interfaces used derive from HBaseRPCProtocolVersion.  It
53    // maintained a single global version number on all HBase Interfaces.  This
54    // meant all HBase RPC was broke though only one of the three RPC Interfaces
55    // had changed.  This has since been undone.
56    // 29:  4/3/2010 - changed ClusterStatus serialization
57    // 30: 3/20/2012 - HBASE-5589: Added offline method 
58  	
59    // NOTE: Not bumped from 29 to maintain compatibility since this addition is
60    // after the v0.92.0 releases this is applied to.  This is not bumped for
61    // 0.94.0 to maintain rolling restart compatibility with 0.92.x. 
62    public static final long VERSION = 29L;
63  
64    /** @return true if master is available */
65    public boolean isMasterRunning();
66  
67    // Admin tools would use these cmds
68  
69    /**
70     * Creates a new table asynchronously.  If splitKeys are specified, then the
71     * table will be created with an initial set of multiple regions.
72     * If splitKeys is null, the table will be created with a single region.
73     * @param desc table descriptor
74     * @param splitKeys
75     * @throws IOException
76     */
77    public void createTable(HTableDescriptor desc, byte [][] splitKeys)
78    throws IOException;
79  
80    /**
81     * Deletes a table
82     * @param tableName table to delete
83     * @throws IOException e
84     */
85    public void deleteTable(final byte [] tableName) throws IOException;
86  
87    /**
88     * Used by the client to get the number of regions that have received the
89     * updated schema
90     *
91     * @param tableName
92     * @return Pair indicating the number of regions updated Pair.getFirst() is the
93     *         regions that are yet to be updated Pair.getSecond() is the total number
94     *         of regions of the table
95     * @throws IOException
96     */
97    public Pair<Integer, Integer> getAlterStatus(byte[] tableName)
98    throws IOException;
99  
100   /**
101    * Adds a column to the specified table
102    * @param tableName table to modify
103    * @param column column descriptor
104    * @throws IOException e
105    */
106   public void addColumn(final byte [] tableName, HColumnDescriptor column)
107   throws IOException;
108 
109   /**
110    * Modifies an existing column on the specified table
111    * @param tableName table name
112    * @param descriptor new column descriptor
113    * @throws IOException e
114    */
115   public void modifyColumn(final byte [] tableName, HColumnDescriptor descriptor)
116   throws IOException;
117 
118 
119   /**
120    * Deletes a column from the specified table. Table must be disabled.
121    * @param tableName table to alter
122    * @param columnName column family to remove
123    * @throws IOException e
124    */
125   public void deleteColumn(final byte [] tableName, final byte [] columnName)
126   throws IOException;
127 
128   /**
129    * Puts the table on-line (only needed if table has been previously taken offline)
130    * @param tableName table to enable
131    * @throws IOException e
132    */
133   public void enableTable(final byte [] tableName) throws IOException;
134 
135   /**
136    * Take table offline
137    *
138    * @param tableName table to take offline
139    * @throws IOException e
140    */
141   public void disableTable(final byte [] tableName) throws IOException;
142 
143   /**
144    * Modify a table's metadata
145    *
146    * @param tableName table to modify
147    * @param htd new descriptor for table
148    * @throws IOException e
149    */
150   public void modifyTable(byte[] tableName, HTableDescriptor htd)
151   throws IOException;
152 
153   /**
154    * Shutdown an HBase cluster.
155    * @throws IOException e
156    */
157   public void shutdown() throws IOException;
158 
159   /**
160    * Stop HBase Master only.
161    * Does not shutdown the cluster.
162    * @throws IOException e
163    */
164   public void stopMaster() throws IOException;
165 
166   /**
167    * Return cluster status.
168    * @return status object
169    */
170   public ClusterStatus getClusterStatus();
171 
172 
173   /**
174    * Move the region <code>r</code> to <code>dest</code>.
175    * @param encodedRegionName The encoded region name; i.e. the hash that makes
176    * up the region name suffix: e.g. if regionname is
177    * <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>,
178    * then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>.
179    * @param destServerName The servername of the destination regionserver.  If
180    * passed the empty byte array we'll assign to a random server.  A server name
181    * is made of host, port and startcode.  Here is an example:
182    * <code> host187.example.com,60020,1289493121758</code>.
183    * @throws UnknownRegionException Thrown if we can't find a region named
184    * <code>encodedRegionName</code>
185    */
186   public void move(final byte [] encodedRegionName, final byte [] destServerName)
187   throws UnknownRegionException;
188 
189   /**
190    * Assign a region to a server chosen at random.
191    * @param regionName Region to assign.  Will use existing RegionPlan if one
192    * found.
193    * @param force If true, will force the assignment.
194    * @throws IOException
195    * @deprecated The <code>force</code> is unused.Use {@link #assign(byte[])}
196    */
197   public void assign(final byte [] regionName, final boolean force)
198   throws IOException;
199 
200   /**
201    * Assign a region to a server chosen at random.
202    * 
203    * @param regionName
204    *          Region to assign. Will use existing RegionPlan if one found.
205    * @throws IOException
206    */
207   public void assign(final byte[] regionName) throws IOException;
208   
209   /**
210    * Unassign a region from current hosting regionserver.  Region will then be
211    * assigned to a regionserver chosen at random.  Region could be reassigned
212    * back to the same server.  Use {@link #move(byte[], byte[])} if you want
213    * to control the region movement.
214    * @param regionName Region to unassign. Will clear any existing RegionPlan
215    * if one found.
216    * @param force If true, force unassign (Will remove region from
217    * regions-in-transition too if present as well as from assigned regions --
218    * radical!.If results in double assignment use hbck -fix to resolve.
219    * @throws IOException
220    */
221   public void unassign(final byte [] regionName, final boolean force)
222   throws IOException;
223 
224   /**
225    * Offline a region from the assignment manager's in-memory state.  The
226    * region should be in a closed state and there will be no attempt to
227    * automatically reassign the region as in unassign.   This is a special
228    * method, and should only be used by experts or hbck.
229    * @param regionName Region to offline.  Will clear any existing RegionPlan
230    * if one found.
231    * @throws IOException
232    */
233   public void offline(final byte[] regionName) throws IOException;
234 
235   /**
236    * Run the balancer.  Will run the balancer and if regions to move, it will
237    * go ahead and do the reassignments.  Can NOT run for various reasons.  Check
238    * logs.
239    * @return True if balancer ran and was able to tell the region servers to
240    * unassign all the regions to balance (the re-assignment itself is async),
241    * false otherwise.
242    */
243   public boolean balance();
244 
245   /**
246    * Turn the load balancer on or off.
247    * @param b If true, enable balancer. If false, disable balancer.
248    * @return Previous balancer value
249    */
250   public boolean balanceSwitch(final boolean b);
251 
252   /**
253    * Turn the load balancer on or off.
254    * It waits until current balance() call, if outstanding, to return.
255    * @param b If true, enable balancer. If false, disable balancer.
256    * @return Previous balancer value
257    */
258   public boolean synchronousBalanceSwitch(final boolean b);
259 
260   /**
261    * Get array of all HTDs.
262    * @return array of HTableDescriptor
263    */
264   public HTableDescriptor[] getHTableDescriptors();
265 
266   /**
267    * Get array of HTDs for requested tables.
268    * @param tableNames
269    * @return array of HTableDescriptor
270    */
271   public HTableDescriptor[] getHTableDescriptors(List<String> tableNames);
272 
273   /**
274    * Executes a single {@link org.apache.hadoop.hbase.ipc.CoprocessorProtocol}
275    * method using the registered protocol handlers.
276    * {@link CoprocessorProtocol} implementations must be registered via the
277    * {@link org.apache.hadoop.hbase.master.MasterServices#registerProtocol(Class, CoprocessorProtocol)}
278    * method before they are available.
279    *
280    * @param call an {@code Exec} instance identifying the protocol, method name,
281    *     and parameters for the method invocation
282    * @return an {@code ExecResult} instance containing the region name of the
283    *     invocation and the return value
284    * @throws IOException if no registered protocol handler is found or an error
285    *     occurs during the invocation
286    * @see org.apache.hadoop.hbase.master.MasterServices#registerProtocol(Class, CoprocessorProtocol)
287    */
288   public ExecResult execCoprocessor(Exec call)
289       throws IOException;
290 
291   public long snapshot(final HSnapshotDescription snapshot)
292     throws IOException;
293 
294   public List<HSnapshotDescription> getCompletedSnapshots()
295     throws IOException;
296 
297   public void deleteSnapshot(final HSnapshotDescription snapshot)
298     throws IOException;
299 
300   public boolean isSnapshotDone(final HSnapshotDescription snapshot)
301     throws IOException;
302 
303   public void restoreSnapshot(final HSnapshotDescription request)
304     throws IOException;
305 
306   public boolean isRestoreSnapshotDone(final HSnapshotDescription request)
307     throws IOException;
308 }