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.security.TokenInfo;
30  import org.apache.hadoop.hbase.security.KerberosInfo;
31  import org.apache.hadoop.hbase.util.Pair;
32  
33  /**
34   * Clients interact with the HMasterInterface to gain access to meta-level
35   * HBase functionality, like finding an HRegionServer and creating/destroying
36   * tables.
37   *
38   * <p>NOTE: if you change the interface, you must change the RPC version
39   * number in HBaseRPCProtocolVersion
40   *
41   */
42  @KerberosInfo(
43      serverPrincipal = "hbase.master.kerberos.principal")
44  @TokenInfo("HBASE_AUTH_TOKEN")
45  public interface HMasterInterface extends VersionedProtocol {
46    /**
47     * This Interfaces' version. Version changes when the Interface changes.
48     */
49    // All HBase Interfaces used derive from HBaseRPCProtocolVersion.  It
50    // maintained a single global version number on all HBase Interfaces.  This
51    // meant all HBase RPC was broke though only one of the three RPC Interfaces
52    // had changed.  This has since been undone.
53    // 29:  4/3/2010 - changed ClusterStatus serialization
54    public static final long VERSION = 29L;
55  
56    /** @return true if master is available */
57    public boolean isMasterRunning();
58  
59    // Admin tools would use these cmds
60  
61    /**
62     * Creates a new table asynchronously.  If splitKeys are specified, then the
63     * table will be created with an initial set of multiple regions.
64     * If splitKeys is null, the table will be created with a single region.
65     * @param desc table descriptor
66     * @param splitKeys
67     * @throws IOException
68     */
69    public void createTable(HTableDescriptor desc, byte [][] splitKeys)
70    throws IOException;
71  
72    /**
73     * Deletes a table
74     * @param tableName table to delete
75     * @throws IOException e
76     */
77    public void deleteTable(final byte [] tableName) throws IOException;
78  
79    /**
80     * Used by the client to get the number of regions that have received the
81     * updated schema
82     *
83     * @param tableName
84     * @return Pair indicating the number of regions updated Pair.getFirst() is the
85     *         regions that are yet to be updated Pair.getSecond() is the total number
86     *         of regions of the table
87     * @throws IOException
88     */
89    public Pair<Integer, Integer> getAlterStatus(byte[] tableName)
90    throws IOException;
91  
92    /**
93     * Adds a column to the specified table
94     * @param tableName table to modify
95     * @param column column descriptor
96     * @throws IOException e
97     */
98    public void addColumn(final byte [] tableName, HColumnDescriptor column)
99    throws IOException;
100 
101   /**
102    * Modifies an existing column on the specified table
103    * @param tableName table name
104    * @param descriptor new column descriptor
105    * @throws IOException e
106    */
107   public void modifyColumn(final byte [] tableName, HColumnDescriptor descriptor)
108   throws IOException;
109 
110 
111   /**
112    * Deletes a column from the specified table. Table must be disabled.
113    * @param tableName table to alter
114    * @param columnName column family to remove
115    * @throws IOException e
116    */
117   public void deleteColumn(final byte [] tableName, final byte [] columnName)
118   throws IOException;
119 
120   /**
121    * Puts the table on-line (only needed if table has been previously taken offline)
122    * @param tableName table to enable
123    * @throws IOException e
124    */
125   public void enableTable(final byte [] tableName) throws IOException;
126 
127   /**
128    * Take table offline
129    *
130    * @param tableName table to take offline
131    * @throws IOException e
132    */
133   public void disableTable(final byte [] tableName) throws IOException;
134 
135   /**
136    * Modify a table's metadata
137    *
138    * @param tableName table to modify
139    * @param htd new descriptor for table
140    * @throws IOException e
141    */
142   public void modifyTable(byte[] tableName, HTableDescriptor htd)
143   throws IOException;
144 
145   /**
146    * Shutdown an HBase cluster.
147    * @throws IOException e
148    */
149   public void shutdown() throws IOException;
150 
151   /**
152    * Stop HBase Master only.
153    * Does not shutdown the cluster.
154    * @throws IOException e
155    */
156   public void stopMaster() throws IOException;
157 
158   /**
159    * Return cluster status.
160    * @return status object
161    */
162   public ClusterStatus getClusterStatus();
163 
164 
165   /**
166    * Move the region <code>r</code> to <code>dest</code>.
167    * @param encodedRegionName The encoded region name; i.e. the hash that makes
168    * up the region name suffix: e.g. if regionname is
169    * <code>TestTable,0094429456,1289497600452.527db22f95c8a9e0116f0cc13c680396.</code>,
170    * then the encoded region name is: <code>527db22f95c8a9e0116f0cc13c680396</code>.
171    * @param destServerName The servername of the destination regionserver.  If
172    * passed the empty byte array we'll assign to a random server.  A server name
173    * is made of host, port and startcode.  Here is an example:
174    * <code> host187.example.com,60020,1289493121758</code>.
175    * @throws UnknownRegionException Thrown if we can't find a region named
176    * <code>encodedRegionName</code>
177    */
178   public void move(final byte [] encodedRegionName, final byte [] destServerName)
179   throws UnknownRegionException;
180 
181   /**
182    * Assign a region to a server chosen at random.
183    * @param regionName Region to assign.  Will use existing RegionPlan if one
184    * found.
185    * @param force If true, will force the assignment.
186    * @throws IOException
187    * @deprecated The <code>force</code> is unused.Use {@link #assign(byte[])}
188    */
189   public void assign(final byte [] regionName, final boolean force)
190   throws IOException;
191 
192   /**
193    * Assign a region to a server chosen at random.
194    * 
195    * @param regionName
196    *          Region to assign. Will use existing RegionPlan if one found.
197    * @throws IOException
198    */
199   public void assign(final byte[] regionName) throws IOException;
200   
201   /**
202    * Unassign a region from current hosting regionserver.  Region will then be
203    * assigned to a regionserver chosen at random.  Region could be reassigned
204    * back to the same server.  Use {@link #move(byte[], byte[])} if you want
205    * to control the region movement.
206    * @param regionName Region to unassign. Will clear any existing RegionPlan
207    * if one found.
208    * @param force If true, force unassign (Will remove region from
209    * regions-in-transition too if present as well as from assigned regions --
210    * radical!.If results in double assignment use hbck -fix to resolve.
211    * @throws IOException
212    */
213   public void unassign(final byte [] regionName, final boolean force)
214   throws IOException;
215 
216   /**
217    * Run the balancer.  Will run the balancer and if regions to move, it will
218    * go ahead and do the reassignments.  Can NOT run for various reasons.  Check
219    * logs.
220    * @return True if balancer ran and was able to tell the region servers to
221    * unassign all the regions to balance (the re-assignment itself is async),
222    * false otherwise.
223    */
224   public boolean balance();
225 
226   /**
227    * Turn the load balancer on or off.
228    * @param b If true, enable balancer. If false, disable balancer.
229    * @return Previous balancer value
230    */
231   public boolean balanceSwitch(final boolean b);
232 
233   /**
234    * Get array of all HTDs.
235    * @return array of HTableDescriptor
236    */
237   public HTableDescriptor[] getHTableDescriptors();
238 
239   /**
240    * Get current HTD for a given tablename
241    * @param tableName
242    * @return HTableDescriptor for the table
243    */
244   //public HTableDescriptor getHTableDescriptor(final byte[] tableName);
245 
246   /**
247    * Get array of HTDs for requested tables.
248    * @param tableNames
249    * @return array of HTableDescriptor
250    */
251   public HTableDescriptor[] getHTableDescriptors(List<String> tableNames);
252 
253 }