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    * @throws IOException
170    */
171   public ClusterStatus getClusterStatus();
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    * <p>
263    * NOTE: This interface up to and including 0.94.8 included a getHTableDescriptors which
264    * did not throw IOE. Adding and deleting checked exceptions declared as thrown by a method
265    * does not break binary compatibility, so rolling restart scenarios will work; however,
266    * it will break contract compatibility possibly requiring source code changes upon
267    * next recompilation.
268    * @return array of HTableDescriptor
269    */
270   public HTableDescriptor[] getHTableDescriptors() throws IOException;
271 
272   /**
273    * Get array of HTDs for requested tables.
274    * <p>
275    * NOTE: This interface up to and including 0.94.8 included a getHTableDescriptors which
276    * did not throw IOE. Adding and deleting checked exceptions declared as thrown by a method
277    * does not break binary compatibility, so rolling restart scenarios will work; however,
278    * it will break contract compatibility possibly requiring source code changes upon
279    * next recompilation.
280    * @param tableNames
281    * @return array of HTableDescriptor
282    * @throws IOException 
283    */
284   public HTableDescriptor[] getHTableDescriptors(List<String> tableNames) throws IOException;
285 
286   /**
287    * Executes a single {@link org.apache.hadoop.hbase.ipc.CoprocessorProtocol}
288    * method using the registered protocol handlers.
289    * {@link CoprocessorProtocol} implementations must be registered via the
290    * {@link org.apache.hadoop.hbase.master.MasterServices#registerProtocol(Class, CoprocessorProtocol)}
291    * method before they are available.
292    *
293    * @param call an {@code Exec} instance identifying the protocol, method name,
294    *     and parameters for the method invocation
295    * @return an {@code ExecResult} instance containing the region name of the
296    *     invocation and the return value
297    * @throws IOException if no registered protocol handler is found or an error
298    *     occurs during the invocation
299    * @see org.apache.hadoop.hbase.master.MasterServices#registerProtocol(Class, CoprocessorProtocol)
300    */
301   public ExecResult execCoprocessor(Exec call)
302       throws IOException;
303 
304   public long snapshot(final HSnapshotDescription snapshot)
305     throws IOException;
306 
307   public List<HSnapshotDescription> getCompletedSnapshots()
308     throws IOException;
309 
310   public void deleteSnapshot(final HSnapshotDescription snapshot)
311     throws IOException;
312 
313   public boolean isSnapshotDone(final HSnapshotDescription snapshot)
314     throws IOException;
315 
316   public void restoreSnapshot(final HSnapshotDescription request)
317     throws IOException;
318 
319   public boolean isRestoreSnapshotDone(final HSnapshotDescription request)
320     throws IOException;
321 
322   /**
323    * Return all table names.
324    * @return the list of table names
325    * @throws IOException if an error occurred while getting the list of tables
326    */
327   public String[] getTableNames() throws IOException;
328 }